@agenticmail/core 0.7.0 → 0.7.2

package/README.md

@@ -174,7 +174,7 @@ Full custom domain through Cloudflare. Agents send from `agent@yourdomain.com` w
 4. Stalwart hostname set to the domain (critical for SMTP EHLO greeting)
 5. DKIM signing key generated in Stalwart (selector: `agenticmail`)
 6. DNS records configured: MX (via Email Routing), SPF, DMARC, DKIM TXT, tunnel CNAME
-7. Tunnel started with ingress rules routing traffic to the API server (port 3100) and Stalwart (port 8080)
+7. Tunnel started with ingress rules routing traffic to the API server (port 3829) and Stalwart (port 8080)
 8. Cloudflare Email Routing enabled on the zone
 9. Email Worker deployed — catches all inbound email, base64-encodes the raw RFC822 content, and POSTs it to the AgenticMail inbound webhook with a shared secret
 10. Catch-all Email Routing rule set to route all `*@domain` to the Worker
@@ -410,7 +410,9 @@ Limits: minimum 1 result, maximum 1000 results per query (default 20).
 
 ## Data Storage
 
-AgenticMail uses a SQLite database with WAL mode (Write-Ahead Logging) for better concurrent access and foreign keys enabled for referential integrity. The database is initialized with automatic migrations that run on first access.
+AgenticMail uses Node's built-in **`node:sqlite`** module (stable since Node 22). The database runs with WAL mode (Write-Ahead Logging) for better concurrent access and foreign keys enabled for referential integrity. Automatic migrations run on first `getDatabase()` call.
+
+> **Why `node:sqlite` instead of `better-sqlite3`?** Before `0.7.0` this package depended on `better-sqlite3`, a native module that ships pre-built binaries per `NODE_MODULE_VERSION` and intermittently lags new Node releases. When prebuilds were missing, installers fell back to `node-gyp` compile-from-source — which requires Python, a C++ toolchain, and a working network at install time. `node:sqlite` is part of Node itself, so by definition it always matches the runtime. No prebuilds, no gyp, no native compilation, no Python prereq. The on-disk database format is unchanged (still SQLite 3); existing data files migrate transparently. **Cost:** Node 22+ is now the minimum supported runtime.
 
 **Database location:** `~/.agenticmail/agenticmail.db`
 
@@ -447,14 +449,14 @@ The SetupManager handles getting everything installed and configured for the fir
 - cloudflared — checks managed binary at `~/.agenticmail/bin/cloudflared` or system-wide via `which`
 
 **Automatic installation:**
-- Docker: via Homebrew (`brew install --cask docker`) on macOS, or the official install script on Linux. Opens Docker Desktop on macOS and waits up to 60 seconds for the daemon to start.
+- Docker: via Homebrew (`brew install colima docker docker-compose`) on macOS — **uses Colima, not Docker Desktop**, so there's no GUI gate and no terms-acceptance dialog. On Linux, the official install script. Starts Colima (`colima start --cpu 2 --memory 2 --disk 10`) and waits for the daemon to come up.
 - Stalwart: starts the container via `docker compose up -d` and waits up to 30 seconds for it to be running.
 - cloudflared: downloads the platform-specific binary from GitHub releases (supports macOS ARM/Intel and Linux ARM/Intel). Installs atomically (write to temp file, chmod, rename) at `~/.agenticmail/bin/cloudflared`.
 
 **Configuration generation:**
 - `docker-compose.yml` — Stalwart service with ports 8080 (HTTP admin), 587 (SMTP submission), 143 (IMAP), 25 (SMTP inbound)
 - `stalwart.toml` — Stalwart configuration with RocksDB storage, internal directory, stdout logging, and fallback admin credentials
-- `config.json` — Master key, Stalwart URL/credentials, SMTP/IMAP host/port, API host/port, data directory (written with mode 0600 for security)
+- `config.json` — Master key, Stalwart URL/credentials, SMTP/IMAP host/port, API host (default `127.0.0.1`) and API port (**default `3829`** — chosen to avoid common dev-tool ports like 3000/3100/3200/3300/4000/5000/8000/8080), data directory (written with mode 0600 for security)
 - `.env` — Environment variables (written with mode 0600)
 
 Configuration files are placed in the data directory (default: `~/.agenticmail/`). Calling `initConfig()` is idempotent — it loads existing config if present, but always regenerates Docker files to keep passwords in sync.

package/REFERENCE.md

@@ -825,7 +825,7 @@ class CloudflareClient {
 
 **`createTunnel()`** — Reuses existing tunnel if name matches. Generates random 32-byte secret.
 
-**`createTunnelRoute()`** — Creates ingress: `/api/agenticmail/*` → apiService (port 3100), `*` → primary service (port 8080), catch-all → 404.
+**`createTunnelRoute()`** — Creates ingress: `/api/agenticmail/*` → apiService (port 3829), `*` → primary service (port 8080), catch-all → 404.
 
 **`deployEmailWorker()`** — Multipart form upload with ES module metadata and plain_text env var bindings. Compatibility date: 2024-01-01.
 

package/dist/index.cjs

@@ -894,6 +894,10 @@ var MailReceiver = class {
   async getMailboxInfo(mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
+      try {
+        await this.client.noop();
+      } catch {
+      }
       const status = this.client.mailbox;
       if (!status) {
         return { name: mailbox, exists: 0, recent: 0, unseen: 0 };
@@ -912,12 +916,8 @@ var MailReceiver = class {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
       const envelopes = [];
-      const mb = this.client.mailbox;
-      const total = mb ? mb.exists ?? 0 : 0;
-      if (total === 0) return envelopes;
       const limit = Math.min(Math.max(options?.limit ?? 20, 1), 1e3);
       const offset = Math.max(options?.offset ?? 0, 0);
-      if (offset >= total) return envelopes;
       const allUids = await this.client.search({ all: true }, { uid: true });
       if (!allUids || allUids.length === 0) return envelopes;
       const sortedUids = Array.from(allUids).sort((a, b) => b - a);
@@ -3190,13 +3190,16 @@ function buildInboundSecurityAdvisory(security, attachments) {
 }
 
 // src/storage/db.ts
-var import_node_sqlite = require("sqlite");
+var import_node_module = require("module");
+var import_meta = {};
+var require2 = (0, import_node_module.createRequire)(import_meta.url);
+var { DatabaseSync } = require2("node:sqlite");
 var db = null;
 function getDatabase(config) {
   if (db) return db;
   ensureDataDir(config);
   const dbPath = `${config.dataDir}/agenticmail.db`;
-  db = new import_node_sqlite.DatabaseSync(dbPath);
+  db = new DatabaseSync(dbPath);
   db.exec("PRAGMA journal_mode = WAL");
   db.exec("PRAGMA foreign_keys = ON");
   runMigrations(db);
@@ -3490,7 +3493,7 @@ function runMigrations(database) {
   }
 }
 function createTestDatabase() {
-  const testDb = new import_node_sqlite.DatabaseSync(":memory:");
+  const testDb = new DatabaseSync(":memory:");
   testDb.exec("PRAGMA journal_mode = WAL");
   testDb.exec("PRAGMA foreign_keys = ON");
   for (const sql of Object.values(MIGRATIONS)) {
@@ -7171,8 +7174,8 @@ var import_node_child_process4 = require("child_process");
 var import_node_fs6 = require("fs");
 var import_node_path7 = require("path");
 var import_node_os6 = require("os");
-var import_node_module = require("module");
-var import_meta = {};
+var import_node_module2 = require("module");
+var import_meta2 = {};
 var PLIST_LABEL = "com.agenticmail.server";
 var SYSTEMD_UNIT = "agenticmail.service";
 var ServiceManager = class {
@@ -7216,7 +7219,7 @@ var ServiceManager = class {
    */
   getApiEntryPath() {
     try {
-      const req = (0, import_node_module.createRequire)(import_meta.url);
+      const req = (0, import_node_module2.createRequire)(import_meta2.url);
       const resolved = req.resolve("@agenticmail/api");
       if ((0, import_node_fs6.existsSync)(resolved)) return resolved;
     } catch {
@@ -7272,7 +7275,7 @@ var ServiceManager = class {
    */
   getVersion() {
     try {
-      const req = (0, import_node_module.createRequire)(import_meta.url);
+      const req = (0, import_node_module2.createRequire)(import_meta2.url);
       const pkgJson = req.resolve("@agenticmail/cli/package.json");
       if ((0, import_node_fs6.existsSync)(pkgJson)) {
         const pkg = JSON.parse((0, import_node_fs6.readFileSync)(pkgJson, "utf-8"));

package/dist/index.d.cts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import { DatabaseSync } from 'node:sqlite';
+import * as node_sqlite from 'node:sqlite';
 import { ImapFlow } from 'imapflow';
 
 interface SendMailOptions {
@@ -291,38 +291,8 @@ declare class StalwartAdmin {
     }): Promise<void>;
 }
 
-/**
- * SQLite storage layer for AgenticMail.
- *
- * Migrated from `better-sqlite3` to Node's built-in `node:sqlite` module
- * (stable since Node 22). The migration eliminates native compilation
- * entirely — `better-sqlite3` ships pre-built binaries per
- * NODE_MODULE_VERSION and intermittently lags new Node releases (Node
- * 25.5.0 was a real example: prebuilds missing, node-gyp fails on the
- * fallback compile-from-source path, fresh `npm install -g
- * @agenticmail/cli` fails for users on bleeding-edge Node). `node:sqlite`
- * is part of Node itself, so by definition it always matches the
- * runtime — no prebuilds, no gyp, no binding errors.
- *
- * # API shape differences this file accommodates
- *
- *   - `new DatabaseSync(path)` instead of `new Database(path)`.
- *   - No `db.pragma(x)` — use `db.exec("PRAGMA " + x)`.
- *   - No `db.transaction(fn)` — wrap in BEGIN/COMMIT manually (see
- *     `runTransactionally` below). Migrations are the only transaction
- *     site in core right now; if more callers need transactions later
- *     they should reuse the same helper.
- *   - `stmt.run(...)` still returns `{ changes, lastInsertRowid }`.
- *     One subtle gotcha: `lastInsertRowid` is a `bigint` in node:sqlite
- *     where better-sqlite3 returned a `number`. Consumers that compare
- *     with `===` or pass it to `Number(...)` need to be aware, but no
- *     site inside AgenticMail today does that — all our rowids are
- *     opaque or string-typed.
- *   - The class type is `DatabaseSync`; we re-export it as `Database`
- *     so consumer files can keep saying `Database` instead of plumbing
- *     `DatabaseSync` through everywhere.
- */
-
+declare const DatabaseSync: typeof node_sqlite.DatabaseSync;
+type DatabaseSync = InstanceType<typeof node_sqlite.DatabaseSync>;
 /**
  * Public type alias for the database instance. Consumers should
  * `import { type Database } from '@agenticmail/core'` rather than

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { EventEmitter } from 'node:events';
-import { DatabaseSync } from 'node:sqlite';
+import * as node_sqlite from 'node:sqlite';
 import { ImapFlow } from 'imapflow';
 
 interface SendMailOptions {
@@ -291,38 +291,8 @@ declare class StalwartAdmin {
     }): Promise<void>;
 }
 
-/**
- * SQLite storage layer for AgenticMail.
- *
- * Migrated from `better-sqlite3` to Node's built-in `node:sqlite` module
- * (stable since Node 22). The migration eliminates native compilation
- * entirely — `better-sqlite3` ships pre-built binaries per
- * NODE_MODULE_VERSION and intermittently lags new Node releases (Node
- * 25.5.0 was a real example: prebuilds missing, node-gyp fails on the
- * fallback compile-from-source path, fresh `npm install -g
- * @agenticmail/cli` fails for users on bleeding-edge Node). `node:sqlite`
- * is part of Node itself, so by definition it always matches the
- * runtime — no prebuilds, no gyp, no binding errors.
- *
- * # API shape differences this file accommodates
- *
- *   - `new DatabaseSync(path)` instead of `new Database(path)`.
- *   - No `db.pragma(x)` — use `db.exec("PRAGMA " + x)`.
- *   - No `db.transaction(fn)` — wrap in BEGIN/COMMIT manually (see
- *     `runTransactionally` below). Migrations are the only transaction
- *     site in core right now; if more callers need transactions later
- *     they should reuse the same helper.
- *   - `stmt.run(...)` still returns `{ changes, lastInsertRowid }`.
- *     One subtle gotcha: `lastInsertRowid` is a `bigint` in node:sqlite
- *     where better-sqlite3 returned a `number`. Consumers that compare
- *     with `===` or pass it to `Number(...)` need to be aware, but no
- *     site inside AgenticMail today does that — all our rowids are
- *     opaque or string-typed.
- *   - The class type is `DatabaseSync`; we re-export it as `Database`
- *     so consumer files can keep saying `Database` instead of plumbing
- *     `DatabaseSync` through everywhere.
- */
-
+declare const DatabaseSync: typeof node_sqlite.DatabaseSync;
+type DatabaseSync = InstanceType<typeof node_sqlite.DatabaseSync>;
 /**
  * Public type alias for the database instance. Consumers should
  * `import { type Database } from '@agenticmail/core'` rather than

package/dist/index.js

@@ -140,6 +140,10 @@ var MailReceiver = class {
   async getMailboxInfo(mailbox = "INBOX") {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
+      try {
+        await this.client.noop();
+      } catch {
+      }
       const status = this.client.mailbox;
       if (!status) {
         return { name: mailbox, exists: 0, recent: 0, unseen: 0 };
@@ -158,12 +162,8 @@ var MailReceiver = class {
     const lock = await this.client.getMailboxLock(mailbox);
     try {
       const envelopes = [];
-      const mb = this.client.mailbox;
-      const total = mb ? mb.exists ?? 0 : 0;
-      if (total === 0) return envelopes;
       const limit = Math.min(Math.max(options?.limit ?? 20, 1), 1e3);
       const offset = Math.max(options?.offset ?? 0, 0);
-      if (offset >= total) return envelopes;
       const allUids = await this.client.search({ all: true }, { uid: true });
       if (!allUids || allUids.length === 0) return envelopes;
       const sortedUids = Array.from(allUids).sort((a, b) => b - a);
@@ -2433,7 +2433,9 @@ function buildInboundSecurityAdvisory(security, attachments) {
 }
 
 // src/storage/db.ts
-import { DatabaseSync } from "sqlite";
+import { createRequire } from "module";
+var require2 = createRequire(import.meta.url);
+var { DatabaseSync } = require2("node:sqlite");
 var db = null;
 function getDatabase(config) {
   if (db) return db;
@@ -6413,7 +6415,7 @@ import { execFileSync as execFileSync3, execSync as execSync2 } from "child_proc
 import { existsSync as existsSync6, readFileSync as readFileSync3, writeFileSync as writeFileSync4, unlinkSync, mkdirSync as mkdirSync5, chmodSync } from "fs";
 import { join as join8 } from "path";
 import { homedir as homedir7, platform as platform4 } from "os";
-import { createRequire } from "module";
+import { createRequire as createRequire2 } from "module";
 var PLIST_LABEL = "com.agenticmail.server";
 var SYSTEMD_UNIT = "agenticmail.service";
 var ServiceManager = class {
@@ -6457,7 +6459,7 @@ var ServiceManager = class {
    */
   getApiEntryPath() {
     try {
-      const req = createRequire(import.meta.url);
+      const req = createRequire2(import.meta.url);
       const resolved = req.resolve("@agenticmail/api");
       if (existsSync6(resolved)) return resolved;
     } catch {
@@ -6513,7 +6515,7 @@ var ServiceManager = class {
    */
   getVersion() {
     try {
-      const req = createRequire(import.meta.url);
+      const req = createRequire2(import.meta.url);
       const pkgJson = req.resolve("@agenticmail/cli/package.json");
       if (existsSync6(pkgJson)) {
         const pkg = JSON.parse(readFileSync3(pkgJson, "utf-8"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agenticmail/core",
-  "version": "0.7.0",
+  "version": "0.7.2",
   "description": "Core SDK for AgenticMail — email, SMS, and phone number access for AI agents",
   "type": "module",
   "main": "dist/index.js",
@@ -20,8 +20,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
-    "dev": "tsup src/index.ts --format esm,cjs --dts --watch",
+    "build": "tsup --config tsup.config.ts",
+    "dev": "tsup --config tsup.config.ts --watch",
     "test": "vitest run",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build"