@inboxapi/cli 0.2.17 → 0.2.19

package/claude/hooks/credential-check.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+// InboxAPI Credential Check — SessionStart hook
+// Verifies InboxAPI credentials are present and valid on session startup.
+// Always exits 0 (non-blocking, informational only)
+
+const fs = require("fs");
+const path = require("path");
+
+
+function findCredentials() {
+  const home = process.env.HOME || process.env.USERPROFILE || "";
+  if (!home) return null;
+  const candidates = [];
+
+  // Platform config dir
+  if (process.platform === "darwin") {
+    candidates.push(
+      path.join(home, "Library", "Application Support", "inboxapi", "credentials.json"),
+    );
+  }
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA || "";
+    const localAppData = process.env.LOCALAPPDATA || "";
+    if (appData) candidates.push(path.join(appData, "inboxapi", "credentials.json"));
+    if (localAppData) candidates.push(path.join(localAppData, "inboxapi", "credentials.json"));
+  }
+  candidates.push(path.join(home, ".config", "inboxapi", "credentials.json"));
+  candidates.push(
+    path.join(home, ".local", "inboxapi", "credentials.json"),
+  );
+
+  for (const p of candidates) {
+    if (fs.existsSync(p)) {
+      return p;
+    }
+  }
+  return null;
+}
+
+function main() {
+  const credPath = findCredentials();
+
+  if (!credPath) {
+    process.stderr.write(
+      "\n[InboxAPI] No credentials found. Run `npx -y @inboxapi/cli login` to authenticate.\n\n",
+    );
+    process.exit(0);
+  }
+
+  try {
+    const creds = JSON.parse(fs.readFileSync(credPath, "utf8"));
+    const email = creds.email || creds.account_name || "(unknown)";
+    process.stderr.write(
+      `\n[InboxAPI] Authenticated as: ${email}\n\n`,
+    );
+  } catch {
+    process.stderr.write(
+      "\n[InboxAPI] Credentials file exists but could not be read. Run `npx -y @inboxapi/cli login` to re-authenticate.\n\n",
+    );
+  }
+
+  process.exit(0);
+}
+
+main();

package/claude/hooks/email-activity-logger.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+// InboxAPI Activity Logger — PostToolUse hook
+// Logs all InboxAPI MCP tool usage to .claude/inboxapi-activity.log
+// Always exits 0 (non-blocking)
+
+const fs = require("fs");
+const path = require("path");
+
+function main() {
+  const input = fs.readFileSync(0, "utf8");
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = data.tool_name || "";
+  const toolInput = data.tool_input || {};
+  const cwd = data.cwd || process.cwd();
+
+  // Only log inboxapi tools
+  if (!toolName.includes("inboxapi")) {
+    process.exit(0);
+  }
+
+  const timestamp = new Date().toISOString();
+  const shortName = toolName.replace("mcp__inboxapi__", "");
+
+  // Build a concise log entry (logs identifiers and lengths, not email content)
+  let details = "";
+  switch (shortName) {
+    case "send_email": {
+      const toVal = toolInput.to;
+      const toCount = Array.isArray(toVal) ? toVal.length : toVal ? 1 : 0;
+      details = `to_count=${toCount}, subject_length=${(toolInput.subject || "").length}, body_length=${(toolInput.body || "").length}`;
+      break;
+    }
+    case "send_reply":
+      details = `in_reply_to=${toolInput.in_reply_to || "?"}, body_length=${(toolInput.body || "").length}`;
+      break;
+    case "forward_email": {
+      const fwdTo = toolInput.to;
+      const fwdCount = Array.isArray(fwdTo) ? fwdTo.length : fwdTo ? 1 : 0;
+      details = `message_id=${toolInput.message_id || "?"}, to_count=${fwdCount}`;
+      break;
+    }
+    case "get_email":
+      details = `index=${toolInput.index ?? "?"}, message_id=${toolInput.message_id || "?"}`;
+      break;
+    case "get_emails":
+      details = `limit=${toolInput.limit || "default"}`;
+      break;
+    case "search_emails":
+      details = `query_length=${(toolInput.query || toolInput.subject || toolInput.sender || "").length}`;
+      break;
+    case "get_thread":
+      details = `message_id=${toolInput.message_id || "?"}`;
+      break;
+    default: {
+      const keys = toolInput && typeof toolInput === "object" ? Object.keys(toolInput) : [];
+      details = keys.length ? `fields=${keys.join(",")}` : "fields=<none>";
+      break;
+    }
+  }
+
+  const logLine = `[${timestamp}] ${shortName}: ${details}\n`;
+
+  // Write to log file
+  const logPath = path.join(cwd, ".claude", "inboxapi-activity.log");
+  try {
+    const logDir = path.dirname(logPath);
+    if (!fs.existsSync(logDir)) {
+      fs.mkdirSync(logDir, { recursive: true });
+    }
+    fs.appendFileSync(logPath, logLine);
+  } catch {
+    // Non-critical — don't fail the tool call
+  }
+
+  process.exit(0);
+}
+
+main();

package/claude/hooks/email-send-guard.js

@@ -0,0 +1,69 @@
+#!/usr/bin/env node
+// InboxAPI Email Send Guard — PreToolUse hook
+// Reviews outbound emails before sending. Logs details to stderr for user visibility.
+// Exit 0 = allow
+
+const fs = require("fs");
+
+function main() {
+  const input = fs.readFileSync(0, "utf8");
+  let data;
+  try {
+    data = JSON.parse(input);
+  } catch {
+    process.exit(0);
+  }
+
+  const toolName = data.tool_name || "";
+  const toolInput = data.tool_input || {};
+
+  // Only inspect send-related tools
+  if (
+    !toolName.includes("send_email") &&
+    !toolName.includes("send_reply") &&
+    !toolName.includes("forward_email")
+  ) {
+    process.exit(0);
+  }
+
+  const rawTo = toolInput.to || toolInput.recipient || "(unknown)";
+  const toList = Array.isArray(rawTo) ? rawTo : [rawTo];
+  const toDisplay = toList.join(", ");
+  const subject = toolInput.subject || "(no subject)";
+  const body = toolInput.body || toolInput.message || "";
+  const action = toolName.includes("forward")
+    ? "FORWARD"
+    : toolName.includes("reply")
+      ? "REPLY"
+      : "SEND";
+
+  // Log details to stderr so the user sees them in the Claude Code UI
+  process.stderr.write(`\n[InboxAPI Send Guard] ${action}\n`);
+  process.stderr.write(`  To:      ${toDisplay}\n`);
+  process.stderr.write(`  Subject: ${subject}\n`);
+  if (body.length > 0) {
+    const preview = body.length > 200 ? body.substring(0, 200) + "..." : body;
+    process.stderr.write(`  Body:    ${preview}\n`);
+  }
+  process.stderr.write("\n");
+
+  // Check for self-send (common AI agent mistake)
+  const hasInboxApiRecipient = toList.some(
+    (addr) => typeof addr === "string" && (addr.includes("@inboxapi.ai") || addr.includes("@inboxapi.com")),
+  );
+  if (hasInboxApiRecipient) {
+    process.stderr.write(
+      `  [WARNING] Recipient is an @inboxapi address. Did you mean to send to an external address?\n\n`,
+    );
+  }
+
+  // Check for empty body
+  if (body.trim().length === 0) {
+    process.stderr.write(`  [WARNING] Email body is empty.\n\n`);
+  }
+
+  // Allow by default — the user sees the preview and can deny via Claude Code's permission prompt
+  process.exit(0);
+}
+
+main();

package/claude/skills/check-inbox/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: check-inbox
+description: Check your InboxAPI email inbox and display a summary of recent messages. Use when the user wants to see their emails, check mail, or view their inbox.
+user-invocable: true
+argument-hint: [limit]
+---
+
+# Check Inbox
+
+Fetch and display a summary of recent emails from the user's InboxAPI inbox.
+
+## Steps
+
+1. Call the `mcp__inboxapi__whoami` tool to identify the current account and email address
+2. Call `mcp__inboxapi__get_email_count` to show the total number of emails
+3. Call `mcp__inboxapi__get_emails` with:
+   - `limit`: Use `$ARGUMENTS` if provided, otherwise default to `20`
+4. Present results in a formatted table with columns:
+   - **From** — sender name or address
+   - **Subject** — email subject line (truncated to 60 chars)
+   - **Date** — received date in relative format (e.g., "2 hours ago", "yesterday")
+5. After the table, show a summary line: "Showing X of Y emails for <email>"
+
+## Output Format
+
+Use this markdown table format:
+
+```
+| # | From | Subject | Date |
+|---|------|---------|------|
+| 1 | Alice <alice@example.com> | Re: Project update... | 2h ago |
+```
+
+If the inbox is empty, display: "Your inbox is empty. Your email address is <email>."
+
+## Notes
+
+- Do NOT read full email bodies — only show the summary list
+- If the user asks to read a specific email after seeing the list, use `mcp__inboxapi__get_email` with the email ID

package/claude/skills/compose/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: compose
+description: Compose and send an email with guided prompts, addressbook lookup, and send confirmation. Use when the user wants to write and send an email.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: [recipient]
+---
+
+# Compose Email
+
+Guide the user through composing and sending an email safely.
+
+## Steps
+
+1. **Identify sender**: Call `mcp__inboxapi__whoami` to get the current account email address
+
+2. **Resolve recipient**:
+   - If `$ARGUMENTS` is provided, use it as the recipient hint
+   - Call `mcp__inboxapi__get_addressbook` to check for matching contacts
+   - If multiple matches found, ask the user to pick one
+   - If no match, ask the user to confirm or provide the full email address
+
+3. **Collect email details**: Ask the user for:
+   - **To**: Recipient email (pre-filled if resolved above)
+   - **Subject**: Email subject line
+   - **Body**: Email content (plain text)
+
+4. **Preview**: Show the complete email before sending:
+   ```
+   From: <your-email@inboxapi.ai>
+   To: <recipient@example.com>
+   Subject: <subject>
+   ---
+   <body>
+   ```
+
+5. **Safety checks**:
+   - Warn if the recipient address matches the sender's own @inboxapi.ai address
+   - Warn if the body is empty
+   - Warn if the subject is empty
+
+6. **Confirm**: Ask the user to confirm: "Send this email? (yes/no)"
+
+7. **Send**: Call `mcp__inboxapi__send_email` with `to`, `subject`, and `body`
+
+8. **Confirm delivery**: Report the result to the user
+
+## Rules
+
+- ALWAYS show a preview before sending
+- ALWAYS ask for explicit confirmation before calling send_email
+- NEVER send an email without the user confirming
+- If the user cancels, acknowledge and do not send

package/claude/skills/email-digest/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: email-digest
+description: Generate a digest summary of recent email activity grouped by thread. Use when the user wants an overview of their email activity.
+user-invocable: true
+argument-hint: [timeframe]
+---
+
+# Email Digest
+
+Generate a structured digest of recent email activity.
+
+## Steps
+
+1. **Determine timeframe**: Use `$ARGUMENTS` if provided (e.g., "today", "this week", "last 3 days"), otherwise default to "last 24 hours"
+
+2. **Get account info**: Call `mcp__inboxapi__whoami` for the account email
+
+3. **Get total count**: Call `mcp__inboxapi__get_email_count` for inbox statistics
+
+4. **Fetch recent emails**: Call `mcp__inboxapi__get_emails` with an appropriate limit (50 for digest)
+
+5. **Group by thread**: For threads with multiple emails, call `mcp__inboxapi__get_thread` to understand the conversation
+
+6. **Generate digest** with these sections:
+
+   ```markdown
+   # Email Digest — <timeframe>
+   Account: <email>
+
+   ## Summary
+   - Total emails in inbox: X
+   - Emails in this period: Y
+   - Unique senders: Z
+   - Threads with activity: N
+
+   ## Active Threads
+   ### 1. <Subject>
+   - Participants: alice@..., bob@...
+   - Messages in period: 3
+   - Latest: "Brief preview of most recent message..."
+   - Status: Awaiting your reply / You replied / FYI only
+
+   ## New Emails (not in threads)
+   | From | Subject | Date |
+   |------|---------|------|
+   | ... | ... | ... |
+
+   ## Needs Attention
+   - Emails you haven't replied to where you were directly addressed
+   ```
+
+7. **Offer actions**: "Would you like to reply to any of these, or read a specific email?"
+
+## Notes
+
+- Focus on actionable insights, not raw data
+- Highlight emails that likely need a response
+- Keep the digest concise — summarize, don't reproduce full emails

package/claude/skills/email-forward/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: email-forward
+description: Forward an email to someone with an optional message. Use when the user wants to forward a specific email to another person.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: [email-id or subject]
+---
+
+# Email Forward
+
+Help the user forward an email to another recipient.
+
+## Steps
+
+1. **Find the email to forward**:
+   - If `$ARGUMENTS` looks like an email ID, call `mcp__inboxapi__get_email` directly
+   - Otherwise, call `mcp__inboxapi__search_emails` with the argument
+   - If multiple results, show them and ask the user to pick one
+
+2. **Show email content**: Display the email being forwarded:
+   ```
+   --- Email to forward ---
+   From: <original sender>
+   Subject: <subject>
+   Date: <date>
+   ---
+   <body preview, first 500 chars>
+   ```
+
+3. **Resolve recipient**:
+   - Ask "Who do you want to forward this to?"
+   - Call `mcp__inboxapi__get_addressbook` to check for matching contacts
+   - Confirm the recipient email address
+
+4. **Optional message**: Ask "Add a message? (or press enter to skip)"
+
+5. **Preview**:
+   ```
+   Forwarding to: <recipient>
+   Subject: Fwd: <original subject>
+   Your message: <optional message or "(none)">
+   Original email from: <sender>, <date>
+   ```
+
+6. **Confirm**: Ask "Forward this email? (yes/no)"
+
+7. **Send**: Call `mcp__inboxapi__forward_email` with the email ID, recipient, and optional message
+
+## Rules
+
+- ALWAYS show what's being forwarded before sending
+- ALWAYS confirm before forwarding
+- NEVER forward without explicit user confirmation

package/claude/skills/email-reply/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: email-reply
+description: Reply to an email with full thread context. Use when the user wants to reply to a specific email or continue an email conversation.
+user-invocable: true
+disable-model-invocation: true
+argument-hint: [email-id or subject]
+---
+
+# Email Reply
+
+Help the user reply to an email with full thread context.
+
+## Steps
+
+1. **Find the email**:
+   - If `$ARGUMENTS` looks like an email ID (alphanumeric string), call `mcp__inboxapi__get_email` directly
+   - Otherwise, call `mcp__inboxapi__search_emails` with the argument as subject/keyword
+   - If multiple results, present them and ask the user to pick one
+
+2. **Load thread context**: Call `mcp__inboxapi__get_thread` with the email's thread ID to show the full conversation
+
+3. **Display thread**: Show the conversation history in chronological order:
+   ```
+   --- Thread: <subject> ---
+
+   [1] From: alice@example.com (Jan 15, 2:30 PM)
+   > Original message text...
+
+   [2] From: you@inboxapi.ai (Jan 15, 3:00 PM)
+   > Your previous reply...
+
+   [3] From: alice@example.com (Jan 15, 4:15 PM)
+   > Latest message you're replying to...
+   ```
+
+4. **Compose reply**: Ask the user what they want to say in their reply
+
+5. **Preview**: Show the reply before sending:
+   ```
+   Replying to: alice@example.com
+   Subject: Re: <subject>
+   ---
+   <reply body>
+   ```
+
+6. **Confirm**: Ask "Send this reply? (yes/no)"
+
+7. **Send**: Call `mcp__inboxapi__send_reply` with the email ID and reply body
+
+## Rules
+
+- ALWAYS show the thread context before composing
+- ALWAYS preview and confirm before sending
+- NEVER send without explicit user confirmation

package/claude/skills/email-search/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: email-search
+description: Search your InboxAPI emails using natural language. Use when the user wants to find specific emails by sender, subject, date, or content.
+user-invocable: true
+argument-hint: [query]
+---
+
+# Email Search
+
+Search emails using natural language and present results clearly.
+
+## Steps
+
+1. Take the user's query from `$ARGUMENTS`
+   - If no arguments provided, ask: "What are you looking for?"
+
+2. Translate the natural language query into a `mcp__inboxapi__search_emails` call:
+   - Extract sender hints (e.g., "from John" -> search by sender)
+   - Extract subject hints (e.g., "about invoices" -> search by subject)
+   - Extract date hints (e.g., "last week", "yesterday")
+   - Use the full query as the search term
+
+3. Call `mcp__inboxapi__search_emails` with the interpreted parameters
+
+4. Present results in a formatted table:
+   ```
+   | # | From | Subject | Date |
+   |---|------|---------|------|
+   ```
+
+5. After showing results, offer: "Would you like to read any of these emails? Provide the number."
+
+6. If the user picks one, call `mcp__inboxapi__get_email` with the email ID
+
+7. If no results, suggest alternative searches or broader terms
+
+## Examples
+
+- `/email-search invoices from accounting` -> search for "invoices" filtered by sender containing "accounting"
+- `/email-search meeting tomorrow` -> search for "meeting" in recent emails
+- `/email-search` -> prompt user for search query

package/claude/skills/setup-inboxapi/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: setup-inboxapi
+description: Set up InboxAPI email tools in your Claude Code project. Adds MCP server config, installs skills, and configures safety hooks. Use when the user wants to configure InboxAPI for their project.
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Setup InboxAPI
+
+Configure InboxAPI email tools for this Claude Code project.
+
+## Steps
+
+1. **Check current setup**: Look for existing `.mcp.json` and `.claude/settings.json` files
+
+2. **Add MCP server** (if not already configured):
+   - Check if `.mcp.json` exists and contains an `inboxapi` entry
+   - If not, run: `claude mcp add inboxapi -- npx -y @inboxapi/cli`
+   - Or create/update `.mcp.json` with:
+     ```json
+     {
+       "mcpServers": {
+         "inboxapi": {
+           "command": "npx",
+           "args": ["-y", "@inboxapi/cli"]
+         }
+       }
+     }
+     ```
+
+3. **Install skills**: Run `npx -y @inboxapi/cli setup-skills` to copy bundled skills and hooks into the project's `.claude/` directory
+
+4. **Verify credentials**:
+   - Call `mcp__inboxapi__whoami` to check if credentials are set up
+   - If not authenticated, instruct the user: "Run `npx -y @inboxapi/cli login` in a terminal to authenticate"
+
+5. **Show summary**:
+   ```
+   InboxAPI Setup Complete!
+
+   MCP Server: configured in .mcp.json
+   Email: <email> (or "not authenticated yet")
+
+   Installed Skills:
+     /check-inbox  — View inbox summary
+     /compose      — Write and send emails
+     /email-search — Search emails
+     /email-reply  — Reply with thread context
+     /email-digest — Email activity digest
+     /email-forward — Forward emails
+
+   Installed Hooks:
+     PreToolUse  — Email send guard (reviews before sending)
+     PostToolUse — Activity logger (audit trail)
+     SessionStart — Credential check (verifies auth on startup)
+
+   Next steps:
+     - Run /check-inbox to see your emails
+     - Run /compose to send your first email
+   ```
+
+## Notes
+
+- This skill is safe to run multiple times — it won't duplicate entries or overwrite local edits
+- Existing `.mcp.json` entries, skill files, and hook files with local edits are preserved
+- `.claude/settings.json` is merged with new hook config (may be reformatted when hooks are updated)
+- Files with local edits are skipped; unmodified files are reported as up to date

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@inboxapi/cli",
-  "version": "0.2.17",
+  "version": "0.2.19",
   "description": "📧 Email for your AI 🤖",
   "main": "index.js",
   "bin": {
     "inboxapi": "index.js"
   },
   "files": [
-    "index.js"
+    "index.js",
+    "claude"
   ],
   "repository": {
     "type": "git",
@@ -27,13 +28,13 @@
     "test": "cargo test"
   },
   "optionalDependencies": {
-    "@inboxapi/cli-darwin-arm64": "0.2.17",
-    "@inboxapi/cli-darwin-x64": "0.2.17",
-    "@inboxapi/cli-linux-arm64": "0.2.17",
-    "@inboxapi/cli-linux-x64": "0.2.17",
-    "@inboxapi/cli-win32-x64": "0.2.17"
+    "@inboxapi/cli-darwin-arm64": "0.2.19",
+    "@inboxapi/cli-darwin-x64": "0.2.19",
+    "@inboxapi/cli-linux-arm64": "0.2.19",
+    "@inboxapi/cli-linux-x64": "0.2.19",
+    "@inboxapi/cli-win32-x64": "0.2.19"
   },
   "dependencies": {
-    "@inboxapi/cli": "^0.2.15"
+    "@inboxapi/cli": "^0.2.19"
   }
 }