@stacksjs/mail 0.3.1

package/dist/index.d.ts

@@ -0,0 +1,126 @@
+/**
+* Get the path to the mail binary for a given platform/arch.
+* Checks the package's bin/ directory first, then falls back to zig-out/.
+*/
+export declare function getBinaryPath(platform?: Platform, arch?: Arch): string | null;
+/**
+* Get the path to the Linux binary for deployment to EC2.
+* This is the primary function used by the deploy script.
+*/
+export declare function getLinuxBinaryPath(arch?: Arch): string | null;
+/**
+* Get the path to the Zig project source for building from source on the server.
+*/
+export declare function getSourcePath(): string;
+/**
+* Build the mail binary for a specific target.
+* Returns the path to the built binary.
+*/
+export declare function buildForTarget(target?: string, optimize?: string): string | null;
+/**
+* Convert a MailServerConfig to environment variables.
+*/
+export declare function configToEnv(config: MailServerConfig): Record<string, string>;
+export declare function createMailAdminClient(options: MailAdminClientOptions): MailAdminClient;
+/**
+* Root of the sibling Zig mail package.
+*/
+export declare const ZIG_PROJECT_ROOT: unknown;
+/**
+* Directory containing pre-built binaries within this package
+*/
+export declare const BIN_DIR: unknown;
+/**
+* Default SMTP server ports
+*/
+export declare const PORTS: {
+  smtp: 25;
+  smtps: 465;
+  submission: 587;
+  imap: 143;
+  imaps: 993;
+  pop3: 110;
+  pop3s: 995
+};
+export declare interface MailServerConfig {
+  host?: string
+  port?: number
+  hostname?: string
+  enableTls?: boolean
+  tlsCert?: string
+  tlsKey?: string
+  enableAuth?: boolean
+  dbPath?: string
+  maxConnections?: number
+  maxMessageSize?: number
+  maxRecipients?: number
+  rateLimitPerIp?: number
+  rateLimitPerUser?: number
+  logLevel?: 'debug' | 'info' | 'warn' | 'error'
+  enableJsonLogging?: boolean
+  mailboxPath?: string
+  backupPath?: string
+  profile?: 'development' | 'staging' | 'production'
+}
+export declare interface MailAdminClientOptions {
+  baseUrl: string
+  username?: string
+  password?: string
+  token?: string
+  fetch?: typeof fetch
+}
+export declare interface MailboxUser {
+  id?: number | string
+  username: string
+  email: string
+  quota_mb?: number
+  used_mb?: number
+  enabled?: boolean
+  created_at?: string
+  last_login?: string
+}
+export declare interface CreateMailboxInput {
+  username: string
+  email: string
+  password: string
+  quota_mb?: number
+}
+export declare interface MailServerStats {
+  messages_received?: number
+  messages_sent?: number
+  messages_queued?: number
+  connections_active?: number
+  [key: string]: unknown
+}
+export declare interface MailServerHealth {
+  status: 'healthy' | 'degraded' | 'unhealthy'
+  version?: string
+  uptime?: number
+  components?: Record<string, { status: string, message?: string }>
+}
+declare type Platform = 'linux' | 'macos' | 'windows';
+declare type Arch = 'x86_64' | 'aarch64';
+export declare class MailAdminError extends Error {
+  public status: number;
+  public body?: unknown;
+  constructor(status: number, message: string, body?: unknown);
+}
+export declare class MailAdminClient {
+  constructor(options: MailAdminClientOptions);
+  listMailboxes(options?: {
+    offset?: number;
+    limit?: number }): Promise<{ users: MailboxUser[];
+    total: number;
+  }>;
+  getMailbox(username: string): Promise<MailboxUser>;
+  createMailbox(input: CreateMailboxInput): Promise<MailboxUser>;
+  updateMailbox(username: string, patch: Partial<Omit<CreateMailboxInput, 'username'>> & { enabled?: boolean }): Promise<MailboxUser>;
+  deleteMailbox(username: string): Promise<{ success: boolean, message?: string }>;
+  ensureMailbox(input: CreateMailboxInput): Promise<{ mailbox: MailboxUser, created: boolean }>;
+  stats(): Promise<MailServerStats>;
+  health(): Promise<MailServerHealth>;
+  queue(options?: { offset?: number, limit?: number, status?: string }): Promise<unknown>;
+  getConfig(): Promise<Record<string, unknown>>;
+  updateConfig(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
+  ensureDomain(domain: string): Promise<{ domain: string, configured: boolean }>;
+}

package/dist/index.js

@@ -0,0 +1,274 @@
+// @bun
+// src/index.ts
+import { existsSync } from "fs";
+import { join, resolve } from "path";
+import { execSync } from "child_process";
+var ZIG_PROJECT_ROOT = resolve(import.meta.dir, "..", "..", "zig");
+var BIN_DIR = join(import.meta.dir, "..", "bin");
+var PORTS = {
+  smtp: 25,
+  smtps: 465,
+  submission: 587,
+  imap: 143,
+  imaps: 993,
+  pop3: 110,
+  pop3s: 995
+};
+function detectPlatform() {
+  switch (process.platform) {
+    case "darwin":
+      return "macos";
+    case "win32":
+      return "windows";
+    default:
+      return "linux";
+  }
+}
+function detectArch() {
+  return process.arch === "arm64" ? "aarch64" : "x86_64";
+}
+function getBinaryPath(platform, arch) {
+  const p = platform || detectPlatform();
+  const a = arch || detectArch();
+  const label = `${a}-${p}`;
+  const packageBinary = join(BIN_DIR, `mail-${label}`);
+  if (existsSync(packageBinary))
+    return packageBinary;
+  const zigOutPaths = [
+    join(ZIG_PROJECT_ROOT, "zig-out", "bin", label, `mail-${label}`),
+    join(ZIG_PROJECT_ROOT, "zig-out", "bin", `mail-${label}`)
+  ];
+  if (p === detectPlatform() && a === detectArch()) {
+    zigOutPaths.push(join(ZIG_PROJECT_ROOT, "zig-out", "bin", "mail"));
+  }
+  for (const path of zigOutPaths) {
+    if (existsSync(path))
+      return path;
+  }
+  return null;
+}
+function getLinuxBinaryPath(arch = "x86_64") {
+  return getBinaryPath("linux", arch);
+}
+function getSourcePath() {
+  return ZIG_PROJECT_ROOT;
+}
+function buildForTarget(target = "x86_64-linux-gnu", optimize = "ReleaseFast") {
+  try {
+    console.log(`Building mail for ${target}...`);
+    execSync(`zig build -Doptimize=${optimize} -Dtarget=${target}`, {
+      cwd: ZIG_PROJECT_ROOT,
+      stdio: "inherit"
+    });
+    const parts = target.split("-");
+    const arch = parts[0];
+    const os = parts[1];
+    const label = `${arch}-${os}`;
+    const possiblePaths = [
+      join(ZIG_PROJECT_ROOT, "zig-out", "bin", label, `mail-${label}`),
+      join(ZIG_PROJECT_ROOT, "zig-out", "bin", `mail-${label}`),
+      join(ZIG_PROJECT_ROOT, "zig-out", "bin", "mail")
+    ];
+    for (const path of possiblePaths) {
+      if (existsSync(path))
+        return path;
+    }
+    return null;
+  } catch (error) {
+    console.error(`Failed to build for ${target}:`, error);
+    return null;
+  }
+}
+function configToEnv(config) {
+  const env = {};
+  if (config.host)
+    env.SMTP_HOST = config.host;
+  if (config.port)
+    env.SMTP_PORT = String(config.port);
+  if (config.hostname)
+    env.SMTP_HOSTNAME = config.hostname;
+  if (config.enableTls !== undefined)
+    env.SMTP_ENABLE_TLS = String(config.enableTls);
+  if (config.tlsCert)
+    env.SMTP_TLS_CERT = config.tlsCert;
+  if (config.tlsKey)
+    env.SMTP_TLS_KEY = config.tlsKey;
+  if (config.enableAuth !== undefined)
+    env.SMTP_ENABLE_AUTH = String(config.enableAuth);
+  if (config.dbPath)
+    env.SMTP_DB_PATH = config.dbPath;
+  if (config.maxConnections)
+    env.SMTP_MAX_CONNECTIONS = String(config.maxConnections);
+  if (config.maxMessageSize)
+    env.SMTP_MAX_MESSAGE_SIZE = String(config.maxMessageSize);
+  if (config.maxRecipients)
+    env.SMTP_MAX_RECIPIENTS = String(config.maxRecipients);
+  if (config.rateLimitPerIp)
+    env.SMTP_RATE_LIMIT_PER_IP = String(config.rateLimitPerIp);
+  if (config.rateLimitPerUser)
+    env.SMTP_RATE_LIMIT_PER_USER = String(config.rateLimitPerUser);
+  if (config.logLevel)
+    env.SMTP_LOG_LEVEL = config.logLevel;
+  if (config.enableJsonLogging !== undefined)
+    env.SMTP_ENABLE_JSON_LOGGING = String(config.enableJsonLogging);
+  if (config.mailboxPath)
+    env.SMTP_MAILBOX_PATH = config.mailboxPath;
+  if (config.backupPath)
+    env.SMTP_BACKUP_PATH = config.backupPath;
+  if (config.profile)
+    env.SMTP_PROFILE = config.profile;
+  return env;
+}
+
+class MailAdminError extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.status = status;
+    this.body = body;
+    this.name = "MailAdminError";
+  }
+}
+
+class MailAdminClient {
+  baseUrl;
+  username;
+  password;
+  token;
+  requestFetch;
+  csrfToken;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.username = options.username;
+    this.password = options.password;
+    this.token = options.token;
+    this.requestFetch = options.fetch ?? fetch;
+  }
+  headers(mutating = false) {
+    const headers = new Headers({ Accept: "application/json" });
+    if (this.token)
+      headers.set("Authorization", `Bearer ${this.token}`);
+    else if (this.username && this.password)
+      headers.set("Authorization", `Basic ${btoa(`${this.username}:${this.password}`)}`);
+    if (mutating)
+      headers.set("Content-Type", "application/json");
+    if (mutating && this.csrfToken)
+      headers.set("X-CSRF-Token", this.csrfToken);
+    return headers;
+  }
+  async csrf() {
+    if (this.csrfToken)
+      return this.csrfToken;
+    const response = await this.requestFetch(`${this.baseUrl}/api/csrf-token`, { headers: this.headers() });
+    const body = await this.readBody(response);
+    if (!response.ok)
+      throw new MailAdminError(response.status, "Unable to acquire mail admin CSRF token", body);
+    const record = body;
+    const token = String(record.csrf_token ?? record.token ?? "");
+    if (!token)
+      throw new MailAdminError(response.status, "Mail admin returned an empty CSRF token", body);
+    this.csrfToken = token;
+    return token;
+  }
+  async readBody(response) {
+    const text = await response.text();
+    if (!text)
+      return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  async request(path, init = {}) {
+    const method = String(init.method ?? "GET").toUpperCase();
+    const mutating = !["GET", "HEAD"].includes(method);
+    if (mutating)
+      await this.csrf();
+    const response = await this.requestFetch(`${this.baseUrl}${path}`, {
+      ...init,
+      headers: this.headers(mutating)
+    });
+    const body = await this.readBody(response);
+    if (!response.ok) {
+      const message = typeof body === "object" && body !== null && "message" in body ? String(body.message) : `Mail admin request failed with HTTP ${response.status}`;
+      throw new MailAdminError(response.status, message, body);
+    }
+    return body;
+  }
+  async listMailboxes(options = {}) {
+    const query = new URLSearchParams;
+    if (options.offset !== undefined)
+      query.set("offset", String(options.offset));
+    if (options.limit !== undefined)
+      query.set("limit", String(options.limit));
+    const result = await this.request(`/api/users${query.size ? `?${query}` : ""}`);
+    return { users: result.users, total: result.total ?? result.count ?? result.users.length };
+  }
+  async getMailbox(username) {
+    return this.request(`/api/users/${encodeURIComponent(username)}`);
+  }
+  async createMailbox(input) {
+    return this.request("/api/users", { method: "POST", body: JSON.stringify(input) });
+  }
+  async updateMailbox(username, patch) {
+    return this.request(`/api/users/${encodeURIComponent(username)}`, { method: "PUT", body: JSON.stringify(patch) });
+  }
+  async deleteMailbox(username) {
+    return this.request(`/api/users/${encodeURIComponent(username)}`, { method: "DELETE" });
+  }
+  async ensureMailbox(input) {
+    try {
+      return { mailbox: await this.getMailbox(input.username), created: false };
+    } catch (error) {
+      if (!(error instanceof MailAdminError) || error.status !== 404)
+        throw error;
+      return { mailbox: await this.createMailbox(input), created: true };
+    }
+  }
+  async stats() {
+    return this.request("/api/stats");
+  }
+  async health() {
+    return this.request("/health");
+  }
+  async queue(options = {}) {
+    const query = new URLSearchParams(Object.entries(options).filter(([, value]) => value !== undefined).map(([key, value]) => [key, String(value)]));
+    return this.request(`/api/queue${query.size ? `?${query}` : ""}`);
+  }
+  async getConfig() {
+    const result = await this.request("/api/config");
+    return typeof result.config === "object" && result.config !== null ? result.config : result;
+  }
+  async updateConfig(patch) {
+    return this.request("/api/config", { method: "PUT", body: JSON.stringify(patch) });
+  }
+  async ensureDomain(domain) {
+    const normalized = domain.trim().toLowerCase();
+    if (!/^(?=.{1,253}$)(?:[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?\.)+[a-z]{2,63}$/.test(normalized))
+      throw new TypeError(`Invalid mail domain: ${domain}`);
+    const config = await this.getConfig();
+    const current = Array.isArray(config.extra_local_domains) ? config.extra_local_domains.map(String) : [];
+    if (current.includes(normalized))
+      return { domain: normalized, configured: false };
+    await this.updateConfig({ extra_local_domains: [...current, normalized] });
+    return { domain: normalized, configured: true };
+  }
+}
+function createMailAdminClient(options) {
+  return new MailAdminClient(options);
+}
+export {
+  getSourcePath,
+  getLinuxBinaryPath,
+  getBinaryPath,
+  createMailAdminClient,
+  configToEnv,
+  buildForTarget,
+  ZIG_PROJECT_ROOT,
+  PORTS,
+  MailAdminError,
+  MailAdminClient,
+  BIN_DIR
+};

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@stacksjs/mail",
+  "type": "module",
+  "version": "0.3.1",
+  "description": "Typed runtime and management client for the mail server",
+  "author": "Chris Breuer",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mail-os/mail.git",
+    "directory": "packages/ts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./dist/index.js",
+      "import": "./dist/index.js"
+    },
+    "./*": {
+      "bun": "./dist/*",
+      "import": "./dist/*"
+    }
+  },
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "README.md",
+    "dist",
+    "bin"
+  ],
+  "scripts": {
+    "build": "bun run build:sdk && bun build.ts",
+    "build:sdk": "bun build src/index.ts --outdir dist --target bun && bun x @stacksjs/dtsx generate --root src --entrypoints index.ts --outdir dist --exclude '**/*.test.ts' --validate",
+    "build:linux-x64": "bun build.ts --target x86_64-linux-gnu",
+    "build:linux-arm64": "bun build.ts --target aarch64-linux-gnu",
+    "build:all": "bun build.ts --all",
+    "prepublishOnly": "bun run build:sdk && bun run build:all"
+  },
+  "devDependencies": {
+    "@stacksjs/dtsx": "^0.11.5"
+  },
+  "keywords": [
+    "smtp",
+    "mail",
+    "email",
+    "server",
+    "zig",
+    "imap",
+    "pop3"
+  ]
+}