commune-ai 0.2.1 → 0.2.4

package/README.md

@@ -1,425 +1,433 @@
-# commune-ai
+# @commune/sdk
 
-**Our email infrastructure**
+Commune is the **communication infrastructure for agents**. It gives your agent a **unified inbox**
+for **email + Slack**, so your agent can talk to humans where they already work. Most teams
+get a working integration in **~15 minutes**.
 
-Build agents that receive emails, reply in threads, access conversation history, and search across all organizational emails. Most teams get their first agent responding in **~15 minutes**.
+## Why Commune exists (what it enables)
+Agents are powerful, but users already live in **email and Slack**. Commune bridges that gap so:
+- your agent is reachable where humans already work
+- you don’t have to build deliverability, threading, or Slack plumbing
+- you can ship an agent‑first experience in minutes, not weeks
 
-## What you get
+In practice, Commune lets you:
+- give an agent a real inbox on your domain
+- respond in the correct email or Slack thread every time
+- use **conversation state** to make smarter, context‑aware replies
 
-1. **Webhook Integration** - Receive emails instantly as structured data
-2. **Thread-aware Replies** - Reply in email conversations with full context
-3. **User History** - Access complete conversation history per user
-4. **Organization Search** - Semantic search across all emails (coming soon)
+## How it works (mental model)
+1) Commune receives inbound email/Slack events.
+2) Commune normalizes them into a **UnifiedMessage**.
+3) Commune sends the UnifiedMessage to your webhook.
+4) Your agent replies using one API call.
 
-> By default, the SDK talks to the hosted Commune API. If you self‑host,
-> pass `baseUrl` to the client.
+> By default, the SDK talks to the hosted Commune API. If you self‑host,\n> pass `baseUrl` to the client.
 
 ---
 
-## Table of Contents
-
-- [Install](#install)
-- [How to Setup (Dashboard Steps)](#how-to-setup-dashboard-steps)
-  - [1. Create and Verify Domain](#1-create-and-verify-domain)
-  - [2. Create Inbox](#2-create-inbox)
-  - [3. Create API Key](#3-create-api-key)
-  - [4. Configure Webhook](#4-configure-webhook)
-  - [5. Environment Variables](#5-environment-variables)
-- [Receive emails](#receive-emails)
-- [Reply in email threads](#reply-in-email-threads)
-- [Access conversation history](#access-conversation-history)
-- [Manage Inboxes Programmatically](#manage-inboxes-programmatically)
-- [Handle different types of emails](#handle-different-types-of-emails)
-- [Semantic Search (Coming Soon)](#semantic-search-coming-soon)
-- [Complete example](#complete-example)
-
----
-
-## Install
-```bash
-npm install commune-ai
-# or
-yarn add commune-ai
-# or
-pnpm add commune-ai
-```
-
----
-
-## How to Setup (Dashboard Steps)
-
-**Before you can receive emails, you need to set up your domain, inbox, and API key in the Commune dashboard.**
-
-### 1. Create and Verify Domain
-1. Go to your [Commune dashboard](https://your-dashboard.com)
-2. Sign up and create an organization
-3. Go to **Domains** → Click **"Add Domain"**
-4. Enter a subdomain (e.g., `agent.yourcompany.com`)
-5. Click **"Create"** - The dashboard will show DNS records to add
-6. Add the DNS records shown in the dashboard to your DNS provider
-7. Click **"Verify"** in the dashboard (wait 5-10 minutes for DNS propagation)
-
-### 2. Create Inbox
-1. In the dashboard, go to **Inboxes**
-2. Click **"Create Inbox"**
-3. Enter a local part (e.g., `support`, `help`, `agent`)
-4. This creates an email address like `support@agent.yourcompany.com`
-5. **Copy the Domain ID and Inbox ID** - you'll need these for your webhook
-
-### 3. Create API Key
-1. Go to **API Keys** in the dashboard
-2. Click **"Create Key"**
-3. Enter a name (e.g., "production-agent")
-4. **Copy the API key immediately** (it only shows once!)
-5. Store it securely as an environment variable
-
-### 4. Configure Webhook
-1. In your domain settings, go to **Webhooks**
-2. Set the webhook endpoint URL to your server's webhook handler
-3. Configure webhook events (usually "email.received")
-4. **Optional:** Set a webhook secret for verification
-
-### 5. Environment Variables
-```bash
-# Required
-COMMUNE_API_KEY=cmk_your_api_key_from_dashboard
-
-# Optional (for self-hosting)
-COMMUNE_BASE_URL=https://your-self-hosted-api.com
-```
-
----
-
-## Receive emails
-
-Emails are sent to your webhook endpoint. Here's how to handle them:
+## Quickstart (end‑to‑end in one file)
+This is the simplest full flow: receive webhook → run agent → reply in thread.
 
 ```ts
-import "dotenv/config";
 import express from "express";
-import { CommuneClient, createWebhookHandler } from "commune-ai";
+import { CommuneClient, createWebhookHandler, verifyCommuneWebhook } from "@commune/sdk";
 
-// Initialize client
-const client = new CommuneClient({
-  apiKey: process.env.COMMUNE_API_KEY,
-});
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
-// Set up your server
-const app = express();
+const handler = createWebhookHandler({
+  verify: ({ rawBody, headers }) => {
+    const signature = headers["x-commune-signature"];
+    const timestamp = headers["x-commune-timestamp"];
+    if (!signature || !timestamp) return false;
 
-// Handle incoming emails at your webhook endpoint
-app.post("/webhook", express.raw({ type: "*/*" }), createWebhookHandler({
-  onEvent: async (message, context) => {
-    console.log(`📧 New email: ${message.content}`);
-
-    // Find sender's email
-    const sender = message.participants.find(p => p.role === "sender")?.identity;
-    if (!sender) return;
-
-    // Reply to the email
-    await client.messages.send({
-      to: sender,
-      text: "Thanks for your email! I'll help with that.",
-      conversation_id: message.conversation_id,
-      domainId: context.payload.domainId,
-      inboxId: context.payload.inboxId,
+    return verifyCommuneWebhook({
+      rawBody,
+      timestamp,
+      signature,
+      secret: process.env.COMMUNE_WEBHOOK_SECRET!,
     });
   },
-}));
-
-app.listen(3000, () => {
-  console.log("Agent listening on port 3000");
+  onEvent: async (message, context) => {
+    // Example inbound payload (unified across email + Slack):
+    // message = {
+    //   channel: "email",
+    //   conversation_id: "thread_id",
+    //   participants: [{ role: "sender", identity: "user@example.com" }],
+    //   content: "Can you help with pricing?"
+    // }
+
+    // --- Run your agent here (1–2 line LLM call) ---
+    const prompt = `Reply to: ${message.content}`;
+    const agentReply = await llm.complete(prompt); // replace with your LLM client
+
+    // Email reply (same thread)
+    if (message.channel === "email") {
+      const sender = message.participants.find(p => p.role === "sender")?.identity;
+      if (!sender) return;
+
+      await client.messages.send({
+        channel: "email",
+        to: sender,
+        text: agentReply,
+        conversation_id: message.conversation_id,
+        domainId: context.payload.domainId,
+        inboxId: context.payload.inboxId,
+      });
+    }
+
+    // Slack reply (same thread)
+    if (message.channel === "slack") {
+      const channelId = message.metadata.slack_channel_id;
+      if (!channelId) return;
+
+      await client.messages.send({
+        channel: "slack",
+        to: channelId,
+        text: agentReply,
+        conversation_id: message.conversation_id, // thread_ts
+      });
+    }
+  },
 });
+
+const app = express();
+app.post("/commune/webhook", express.raw({ type: "*/*" }), handler);
+app.listen(3000, () => console.log("listening on 3000"));
+```
+
+## 0) Install
+```bash
+npm install @commune/sdk
 ```
 
-**Email structure:**
+---
+
+## Unified inbox (what your webhook receives)
+Every inbound email or Slack message arrives in this shape:
+
 ```ts
-interface UnifiedMessage {
-  channel: "email";
+export interface UnifiedMessage {
+  channel: "email" | "slack";
   message_id: string;
-  conversation_id: string; // email thread ID
-  participants: Array<{
-    role: "sender" | "to" | "cc" | "bcc";
-    identity: string; // email address
-  }>;
+  conversation_id: string; // email thread or Slack thread_ts
+  participants: { role: string; identity: string }[];
   content: string;
-  content_html?: string;
-  metadata: {
-    subject?: string;
-    created_at: string;
-    // ... more email metadata
-  };
+  metadata: { slack_channel_id?: string; ... };
 }
 ```
 
 ---
 
-## Reply in email threads
+## API key (required)
+All `/api/*` requests require an API key. Create one in the dashboard and reuse it in your client.
 
-Keep conversations organized by replying in the same email thread:
+```bash
+export COMMUNE_API_KEY="your_key_from_dashboard"
+export COMMUNE_WEBHOOK_SECRET="your_webhook_secret"
+```
 
 ```ts
-app.post("/webhook", express.raw({ type: "*/*" }), createWebhookHandler({
-  onEvent: async (message, context) => {
-    const sender = message.participants.find(p => p.role === "sender")?.identity;
-    if (!sender) return;
-
-    // Reply in the same thread
-    await client.messages.send({
-      to: sender,
-      text: "Thanks for your question!",
-      conversation_id: message.conversation_id, // keeps it in thread
-      domainId: context.payload.domainId,
-      inboxId: context.payload.inboxId,
-    });
-  },
-}));
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 ```
 
 ---
 
----
-
-## Access conversation history
-
-Give your agent full context by accessing different types of email history.
+## Context (conversation state)
+Commune stores conversation state so your agent can respond with context.
 
 ```ts
-import { CommuneClient } from "commune-ai";
-const client = new CommuneClient({
-  apiKey: process.env.COMMUNE_API_KEY,
+import { CommuneClient } from "@commune/sdk";
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
+
+// Thread history (email thread or Slack thread)
+const thread = await client.messages.listByConversation(message.conversation_id, {
+  order: "asc",
+  limit: 50,
 });
 
-// 1) Thread history - all messages in current conversation
-const threadMessages = await client.messages.listByConversation(
-  message.conversation_id,
-  { order: "asc", limit: 20 }
-);
+// All messages from a user
+const userHistory = await client.messages.list({
+  sender: "user@example.com",
+  limit: 25,
+});
 
-// 2) User history - all emails from/to a specific person
-const userEmails = await client.messages.list({
-  sender: "customer@example.com",
+// All messages in a specific inbox
+const inboxMessages = await client.messages.list({
+  inbox_id: "i_xxx",
+  channel: "email",
   limit: 50,
-  order: "desc", // newest first
 });
+```
 
-// 3) Inbox history - all emails in your domain
-const inboxEmails = await client.messages.list({
-  inbox_id: "inbox_123",
-  limit: 100,
-});
+---
+
+## Cross‑channel behavior (email + Slack in one handler)
+The same `UnifiedMessage` shape works for both channels. You only branch on `channel`.
+
+```ts
+import express from "express";
+import { CommuneClient, createWebhookHandler } from "@commune/sdk";
+
+// Hosted API is default. If self-hosted, pass { baseUrl: "https://your-api" }
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
-// 4) Organization search - semantic search across all emails (coming soon)
-const searchResults = await client.search({
-  query: "pricing questions from last week",
-  limit: 10,
-  threshold: 0.8,
+const handler = createWebhookHandler({
+  onEvent: async (message, context) => {
+    if (message.channel === "email") {
+      const sender = message.participants.find(p => p.role === "sender")?.identity;
+      if (!sender) return;
+
+      await client.messages.send({
+        channel: "email",
+        to: sender,
+        text: "Got it — thanks for the message.",
+        conversation_id: message.conversation_id,
+        domainId: context.payload.domainId,
+        inboxId: context.payload.inboxId,
+      });
+    }
+
+    if (message.channel === "slack") {
+      const channelId = message.metadata.slack_channel_id;
+      if (!channelId) return;
+
+      await client.messages.send({
+        channel: "slack",
+        to: channelId,
+        text: "Replying in thread ✅",
+        conversation_id: message.conversation_id,
+      });
+    }
+  },
 });
 
-console.log(`Found ${searchResults.length} relevant emails`);
+const app = express();
+app.post("/commune/webhook", express.raw({ type: "*/*" }), handler);
+app.listen(3000);
 ```
 
 ---
 
-## Manage Inboxes Programmatically
+---
 
-Create and manage email inboxes for your agents programmatically.
+## Setup instructions (dashboard-first)
+Domain setup and inbox creation are done in the **Commune dashboard**. You then copy the
+IDs into your code.
 
-### Create Multiple Inboxes
+### 1) Create a subdomain for the agent
+Use a subdomain like `agents.yourcompany.com` for deliverability and isolation.
 
-Set up different inboxes for different purposes:
+### 2) Create and verify the domain in the dashboard
+The dashboard guides you through DNS (SPF/DKIM/MX) and verification.
 
-```ts
-import { CommuneClient } from "commune-ai";
+### 3) Create inboxes for your agents in the dashboard
+Each inbox represents an agent address (e.g. `support@agents.yourcompany.com`).
 
-const client = new CommuneClient({
-  apiKey: process.env.COMMUNE_API_KEY,
-});
+### 4) Use IDs from the webhook payload
+The webhook payload already includes:
+- `domainId` (e.g. `d_xxx`)
+- `inboxId` (e.g. `i_xxx`)
 
-// Create inboxes for different departments
-async function setupInboxes(domainId: string) {
-  const supportInbox = await client.inboxes.create(domainId, {
-    localPart: "support",  // Creates support@yourdomain.com
-    agent: {
-      id: "support-agent",
-      name: "Support Bot",
-      metadata: { department: "customer-success" }
-    },
-    status: "active",
-  });
-
-  const salesInbox = await client.inboxes.create(domainId, {
-    localPart: "sales",  // Creates sales@yourdomain.com
-    agent: {
-      id: "sales-agent",
-      name: "Sales Bot",
-      metadata: { department: "sales" }
-    },
-    status: "active",
-  });
-
-  return { supportInbox, salesInbox };
-}
+Use them when replying:
+
+```ts
+await client.messages.send({
+  channel: "email",
+  to: "user@example.com",
+  text: "Thanks — replying in thread.",
+  conversation_id: message.conversation_id,
+  domainId: context.payload.domainId,
+  inboxId: context.payload.inboxId,
+});
 ```
 
-### Set Webhooks for Specific Inboxes
+> The SDK also supports programmatic domain/inbox creation, but the dashboard
+> flow is the primary path for most teams.
 
-Configure webhooks per inbox to route emails to different handlers:
+### 5) Set your webhook secret
+When you configure the inbox webhook in the dashboard, Commune shows a **webhook secret**.
+Store it as:
 
-```ts
-async function configureWebhooks(domainId: string, inboxes: any) {
-  // Support inbox webhook
-  await client.inboxes.setWebhook(domainId, inboxes.supportInbox.id, {
-    endpoint: "https://your-api.com/webhooks/support",
-    events: ["email.received"],
-  });
-
-  // Sales inbox webhook
-  await client.inboxes.setWebhook(domainId, inboxes.salesInbox.id, {
-    endpoint: "https://your-api.com/webhooks/sales",
-    events: ["email.received"],
-  });
-}
+```bash
+export COMMUNE_WEBHOOK_SECRET="your_webhook_secret"
 ```
 
-### List and Manage Inboxes
+Use it in the `verify` function shown above.
 
-```ts
-// List all inboxes for a domain
-const inboxes = await client.inboxes.list(domainId);
-console.log(`Found ${inboxes.length} inboxes`);
-
-// Update an inbox
-await client.inboxes.update(domainId, inboxId, {
-  localPart: "help",  // Change from "support" to "help"
-  status: "active",
-});
+### 6) Create an API key in the dashboard
+Use the dashboard to create an API key, then set it as:
 
-// Delete an inbox
-await client.inboxes.remove(domainId, inboxId);
+```bash
+export COMMUNE_API_KEY="your_key_from_dashboard"
 ```
 
 ---
 
-## Handle different inbox emails
+## Structured extraction (per inbox)
+You can attach a **JSON schema** to a specific inbox so Commune extracts structured data from inbound emails.
 
-Set up separate webhook endpoints for different inboxes:
+### 1) Add a schema to an inbox (dashboard)
+In **Dashboard → Inboxes**, open an inbox and add a Structured Extraction schema. Save it and enable extraction.
 
+### 2) Set the schema via SDK (optional)
 ```ts
-const client = new CommuneClient({
-  apiKey: process.env.COMMUNE_API_KEY,
+await client.inboxes.setExtractionSchema({
+  domainId: "domain-123",
+  inboxId: "inbox-456",
+  schema: {
+    name: "invoice_extraction",
+    description: "Extract invoice details",
+    enabled: true,
+    schema: {
+      type: "object",
+      properties: {
+        invoiceNumber: { type: "string" },
+        amount: { type: "number" },
+        dueDate: { type: "string" }
+      },
+      required: ["invoiceNumber", "amount"],
+      additionalProperties: false
+    }
+  }
 });
+```
 
-const app = express();
+### 3) Read extracted data in your webhook
+The webhook payload includes the structured output when extraction is enabled.
 
-// Sales inbox webhook - handles sales@yourdomain.com
-app.post("/webhook/sales", express.raw({ type: "*/*" }), createWebhookHandler({
+```ts
+const handler = createWebhookHandler({
   onEvent: async (message, context) => {
-    const sender = message.participants.find(p => p.role === "sender")?.identity;
-    if (!sender) return;
-
-    await client.messages.send({
-      to: sender,
-      text: "Thanks for your sales inquiry!",
-      conversation_id: message.conversation_id,
-      domainId: context.payload.domainId,
-      inboxId: context.payload.inboxId,
-    });
+    const extracted = context.payload.extractedData
+      || message.metadata?.extracted_data
+      || null;
+
+    if (extracted) {
+      // use structured fields in your agent workflow
+      console.log("Extracted:", extracted);
+    }
   },
-}));
+});
+```
+
+> Tip: Keep your schema minimal (only the fields you need). You can evolve it over time.
+
+### Example: Invoice extraction (end-to-end)
+```ts
+import { CommuneClient, createWebhookHandler } from "@commune/sdk";
+
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
+
+await client.inboxes.setExtractionSchema({
+  domainId: "domain-123",
+  inboxId: "inbox-456",
+  schema: {
+    name: "invoice_extraction",
+    enabled: true,
+    schema: {
+      type: "object",
+      properties: {
+        invoiceNumber: { type: "string" },
+        amount: { type: "number" },
+        vendor: { type: "string" }
+      },
+      required: ["invoiceNumber", "amount"],
+      additionalProperties: false
+    }
+  }
+});
 
-// Marketing inbox webhook - handles marketing@yourdomain.com
-app.post("/webhook/marketing", express.raw({ type: "*/*" }), createWebhookHandler({
+const handler = createWebhookHandler({
   onEvent: async (message, context) => {
-    const sender = message.participants.find(p => p.role === "sender")?.identity;
-    if (!sender) return;
-
-    await client.messages.send({
-      to: sender,
-      text: "Thanks for subscribing to our newsletter!",
-      conversation_id: message.conversation_id,
-      domainId: context.payload.domainId,
-      inboxId: context.payload.inboxId,
-    });
-  },
-}));
+    const extracted = context.payload.extractedData;
+    if (!extracted) return;
+
+    console.log("Invoice:", extracted.invoiceNumber);
+    console.log("Amount:", extracted.amount);
 
-app.listen(3000, () => {
-  console.log("Agent running on port 3000");
+    await processInvoice(extracted);
+  },
 });
 ```
 
 ---
 
-## Semantic Search (Coming Soon)
-
-Search across all emails in your organization using natural language queries.
+## Webhook verification (Commune → your app)
+Commune signs outbound webhooks using your **inbox webhook secret**. Verify the
+signature before processing the request.
 
 ```ts
-import { CommuneClient } from "commune-ai";
-
-const client = new CommuneClient({
-  apiKey: process.env.COMMUNE_API_KEY,
-});
-
-// Find emails similar to a query
-const results = await client.search({
-  query: "What were the pricing questions from last week?",
-  limit: 10,
-  threshold: 0.7, // Similarity threshold 0-1
-  before: "2024-12-31", // Only search emails before this date
-  sender: "customer@example.com", // Filter by sender (optional)
+import { createWebhookHandler, verifyCommuneWebhook } from "@commune/sdk";
+
+const handler = createWebhookHandler({
+  verify: ({ rawBody, headers }) => {
+    const signature = headers["x-commune-signature"];
+    const timestamp = headers["x-commune-timestamp"];
+    if (!signature || !timestamp) return false;
+
+    return verifyCommuneWebhook({
+      rawBody,
+      timestamp,
+      signature,
+      secret: process.env.COMMUNE_WEBHOOK_SECRET!,
+    });
+  },
+  onEvent: async (message) => {
+    // handle verified message
+  },
 });
-
-console.log(`Found ${results.length} relevant emails:`);
-for (const result of results) {
-  console.log(`Match (${result.similarity.toFixed(2)}): ${result.message.content}`);
-  console.log(`Highlights: ${result.highlights.join(", ")}`);
-}
 ```
 
-**What you get:**
-- **Natural language queries** - Search like "pricing issues from enterprise customers"
-- **Similarity scores** - Ranked results by relevance (0-1)
-- **Highlighted matches** - Text snippets showing why the email matched
-- **Filtering options** - By date range, sender, or other criteria
-- **Fast results** - AI-powered semantic matching
-
 ---
 
-## Complete example
-
-A simple email agent that receives emails and replies:
+## Full example (single file)
+A complete copy‑paste example that:
+- receives webhook
+- replies by email
+- replies in Slack thread
+- fetches conversation history
 
 ```ts
-import "dotenv/config";
 import express from "express";
-import { CommuneClient, createWebhookHandler } from "commune-ai";
-
-const client = new CommuneClient({
-  apiKey: process.env.COMMUNE_API_KEY,
-});
+import { CommuneClient, createWebhookHandler } from "@commune/sdk";
 
-const app = express();
+const client = new CommuneClient({ apiKey: process.env.COMMUNE_API_KEY! });
 
-app.post("/webhook", express.raw({ type: "*/*" }), createWebhookHandler({
+const handler = createWebhookHandler({
   onEvent: async (message, context) => {
-    // Get the sender's email address
-    const sender = message.participants.find(p => p.role === "sender")?.identity;
-    if (!sender) return;
-
-    // Reply to the email
-    await client.messages.send({
-      to: sender,
-      text: "Thanks for your email! I'll get back to you soon.",
-      conversation_id: message.conversation_id,
-      domainId: context.payload.domainId,
-      inboxId: context.payload.inboxId,
-    });
+    // 1) Email reply (same thread)
+    if (message.channel === "email") {
+      const sender = message.participants.find(p => p.role === "sender")?.identity;
+      if (!sender) return;
+
+      await client.messages.send({
+        channel: "email",
+        to: sender,
+        text: "Thanks! We received your email.",
+        conversation_id: message.conversation_id,
+        domainId: context.payload.domainId,
+        inboxId: context.payload.inboxId,
+      });
+
+      return;
+    }
+
+    // 2) Slack reply (same thread)
+    if (message.channel === "slack") {
+      const channelId = message.metadata.slack_channel_id;
+      if (!channelId) return;
+
+      await client.messages.send({
+        channel: "slack",
+        to: channelId,
+        text: "Thanks! Replying in thread.",
+        conversation_id: message.conversation_id,
+      });
+    }
   },
-}));
-
-app.listen(3000, () => {
-  console.log("Email agent running on port 3000");
 });
+
+const app = express();
+app.post("/commune/webhook", express.raw({ type: "*/*" }), handler);
+app.listen(3000, () => console.log("listening on 3000"));
 ```

package/dist/client.d.ts

@@ -19,11 +19,6 @@ export declare class CommuneClient {
         verify: (domainId: string) => Promise<Record<string, unknown>>;
         records: (domainId: string) => Promise<unknown[]>;
         status: (domainId: string) => Promise<Record<string, unknown>>;
-        createWebhook: (domainId: string, payload?: {
-            endpoint?: string;
-            events?: string[];
-        }) => Promise<Record<string, unknown>>;
-        saveWebhookSecret: (domainId: string, secret: string) => Promise<Record<string, unknown>>;
     };
     inboxes: {
         list: (domainId: string) => Promise<InboxEntry[]>;
@@ -46,6 +41,20 @@ export declare class CommuneClient {
             endpoint: string;
             events?: string[];
         }) => Promise<InboxEntry>;
+        setExtractionSchema: (payload: {
+            domainId: string;
+            inboxId: string;
+            schema: {
+                name: string;
+                description?: string;
+                enabled?: boolean;
+                schema: Record<string, any>;
+            };
+        }) => Promise<InboxEntry>;
+        removeExtractionSchema: (payload: {
+            domainId: string;
+            inboxId: string;
+        }) => Promise<InboxEntry>;
     };
     messages: {
         send: (payload: SendMessagePayload) => Promise<Record<string, unknown>>;

package/dist/client.js

@@ -38,15 +38,6 @@ export class CommuneClient {
             status: async (domainId) => {
                 return this.request(`/api/domains/${encodeURIComponent(domainId)}/status`);
             },
-            createWebhook: async (domainId, payload) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/webhook`, {
-                    method: 'POST',
-                    json: payload,
-                });
-            },
-            saveWebhookSecret: async (domainId, secret) => {
-                return this.request(`/api/domains/${encodeURIComponent(domainId)}/webhook/secret`, { method: 'POST', json: { secret } });
-            },
         };
         this.inboxes = {
             list: async (domainId) => {
@@ -70,14 +61,20 @@ export class CommuneClient {
             setWebhook: async (domainId, inboxId, payload) => {
                 return this.request(`/api/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 });
+            },
+            removeExtractionSchema: async (payload) => {
+                const { domainId, inboxId } = payload;
+                return this.request(`/api/domains/${encodeURIComponent(domainId)}/inboxes/${encodeURIComponent(inboxId)}/extraction-schema`, { method: 'DELETE' });
+            },
         };
         this.messages = {
             send: async (payload) => {
-                // Always send as email (Slack support coming soon)
-                const emailPayload = { ...payload, channel: 'email' };
                 return this.request('/api/messages/send', {
                     method: 'POST',
-                    json: emailPayload,
+                    json: payload,
                 });
             },
             list: async (params) => {
@@ -99,10 +96,8 @@ export class CommuneClient {
                 })}`);
             },
         };
-        // Semantic search across all organizational emails (coming soon)
+        // Semantic search across all organizational emails
         this.search = async (params) => {
-            // Placeholder for future semantic search implementation
-            // This will search across all emails in the organization
             return this.request(`/api/search${buildQuery({
                 q: params.query,
                 limit: params.limit || 10,
@@ -117,9 +112,6 @@ export class CommuneClient {
                 return this.request(`/api/attachments/${encodeURIComponent(attachmentId)}`);
             },
         };
-        if (!options.apiKey) {
-            throw new Error('API key is required. Get one from your Commune dashboard at https://commune.ai');
-        }
         this.baseUrl = (options.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
         this.apiKey = options.apiKey;
         this.headers = options.headers;

package/dist/index.d.ts

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

package/dist/index.js

@@ -1,4 +1,3 @@
 export { CommuneClient } from './client.js';
 export { verifyResendWebhook } from './webhooks.js';
-// export { verifySlackWebhook } from './webhooks.js'; // Slack support coming soon
 export { createWebhookHandler } from './listener.js';

package/dist/listener.js

@@ -49,6 +49,7 @@ export const createWebhookHandler = ({ onEvent, verify }) => {
         const headers = isWebRequest
             ? {
                 'x-commune-signature': req.headers.get('x-commune-signature') || undefined,
+                'x-commune-timestamp': req.headers.get('x-commune-timestamp') || undefined,
             }
             : getHeadersFromNode(req);
         if (verify && !verify({ rawBody, headers })) {

package/dist/types.d.ts

@@ -17,6 +17,7 @@ export interface MessageMetadata {
     message_id?: string | null;
     provider?: 'resend' | 'email' | string;
     raw?: unknown;
+    extracted_data?: Record<string, any>;
 }
 export interface UnifiedMessage {
     _id?: string;
@@ -51,6 +52,7 @@ export interface DomainWebhook {
 export interface InboxWebhook {
     endpoint?: string;
     events?: string[];
+    secret?: string;
 }
 export interface InboxEntry {
     id: string;
@@ -62,6 +64,12 @@ export interface InboxEntry {
         metadata?: Record<string, unknown>;
     };
     webhook?: InboxWebhook;
+    extractionSchema?: {
+        name: string;
+        description?: string;
+        schema: Record<string, any>;
+        enabled: boolean;
+    };
     createdAt?: string;
     status?: string;
 }
@@ -131,6 +139,7 @@ export interface InboundEmailWebhookPayload {
     event: unknown;
     email: unknown;
     message: UnifiedMessage;
+    extractedData?: Record<string, any>;
 }
 export interface ApiError {
     message?: string;

package/dist/webhooks.js

@@ -8,30 +8,3 @@ export const verifyResendWebhook = (payload, headers, secret) => {
     };
     return webhook.verify(payload, svixHeaders);
 };
-// Slack webhook verification (coming soon)
-// export const verifySlackWebhook = ({
-//   rawBody,
-//   timestamp,
-//   signature,
-//   signingSecret,
-// }: {
-//   rawBody: string;
-//   timestamp: string;
-//   signature: string;
-//   signingSecret: string;
-// }) => {
-//   const baseString = `v0:${timestamp}:${rawBody}`;
-//   const hmac = crypto
-//     .createHmac('sha256', signingSecret)
-//     .update(baseString, 'utf8')
-//     .digest('hex');
-//
-//   const expected = `v0=${hmac}`;
-//   const expectedBuffer = Buffer.from(expected, 'utf8');
-//   const signatureBuffer = Buffer.from(signature, 'utf8');
-//   if (expectedBuffer.length !== signatureBuffer.length) {
-//     return false;
-//   }
-//
-//   return crypto.timingSafeEqual(expectedBuffer, signatureBuffer);
-// };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commune-ai",
-  "version": "0.2.1",
+  "version": "0.2.4",
   "description": "Our email infrastructure - webhooks, threads, history, and semantic search",
   "type": "module",
   "main": "dist/index.js",
@@ -15,9 +15,30 @@
     "dist",
     "README.md"
   ],
+  "keywords": [
+    "email",
+    "slack",
+    "ai",
+    "agent",
+    "webhook",
+    "communication",
+    "inbox",
+    "api"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/commune-ai/commune"
+  },
+  "homepage": "https://github.com/commune-ai/commune#readme",
+  "bugs": {
+    "url": "https://github.com/commune-ai/commune/issues"
+  },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "prepack": "npm run build"
   },
   "dependencies": {
     "svix": "^1.44.0"