botinabox 0.5.2 → 0.5.3

package/README.md

@@ -241,6 +241,12 @@ botinabox/
 └── tsconfig.json
 ```
 
+## Staying up to date
+
+**CLI users:** The `botinabox` CLI checks for new versions automatically and prints a notice when an update is available. Run `botinabox update` to upgrade in place. Alternatively, use `npx botinabox` to always run the latest version without a global install.
+
+**Library consumers:** By default, `npm install botinabox` adds a `^` semver range to your `package.json`, so patch and minor updates are picked up on your next `npm install`. For fully automated dependency updates, set up [Dependabot](https://docs.github.com/en/code-security/dependabot) or [Renovate](https://github.com/renovatebot/renovate) — they'll create PRs in your repo whenever a new version is published.
+
 ## License
 
 MIT

package/dist/chunk-3X3YKI4T.js

@@ -0,0 +1,357 @@
+// src/connectors/google/oauth.ts
+var _google;
+async function getGoogle() {
+  if (!_google) {
+    try {
+      const mod = await import("googleapis");
+      _google = mod.google;
+    } catch {
+      throw new Error(
+        "googleapis is required for Google connectors. Install it: npm install googleapis"
+      );
+    }
+  }
+  return _google;
+}
+async function createOAuth2Client(config) {
+  const google = await getGoogle();
+  return new google.auth.OAuth2(
+    config.clientId,
+    config.clientSecret,
+    config.redirectUri
+  );
+}
+function getAuthUrl(client, scopes) {
+  return client.generateAuthUrl({
+    access_type: "offline",
+    prompt: "consent",
+    scope: scopes
+  });
+}
+async function exchangeCode(client, code) {
+  const { tokens } = await client.getToken(code);
+  return tokens;
+}
+async function createServiceAccountClient(config, scopes) {
+  const google = await getGoogle();
+  const auth = new google.auth.GoogleAuth({
+    ...config.keyFile ? { keyFile: config.keyFile } : {},
+    ...config.credentials ? { credentials: config.credentials } : {},
+    scopes,
+    clientOptions: { subject: config.subject }
+  });
+  return auth.getClient();
+}
+async function loadTokens(getter, accountKey) {
+  const raw = await getter(`google_tokens:${accountKey}`);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function saveTokens(setter, accountKey, tokens) {
+  await setter(`google_tokens:${accountKey}`, JSON.stringify(tokens));
+}
+async function refreshIfNeeded(client, tokens, saver) {
+  const buffer = 6e4;
+  const isExpired = tokens.expiry_date != null && Date.now() >= tokens.expiry_date - buffer;
+  if (!isExpired) return tokens;
+  client.setCredentials(tokens);
+  const { credentials } = await client.refreshAccessToken();
+  const refreshed = {
+    access_token: credentials.access_token,
+    refresh_token: credentials.refresh_token ?? tokens.refresh_token,
+    expiry_date: credentials.expiry_date ?? void 0,
+    token_type: credentials.token_type ?? "Bearer"
+  };
+  if (saver) {
+    await saver(refreshed);
+  }
+  return refreshed;
+}
+
+// src/connectors/google/gmail-connector.ts
+var GoogleGmailConnector = class {
+  id = "google-gmail";
+  meta = {
+    displayName: "Google Gmail",
+    provider: "google",
+    dataType: "email"
+  };
+  tokenLoader;
+  tokenSaver;
+  client = null;
+  config = null;
+  tokens = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  gmail = null;
+  constructor(opts = {}) {
+    this.tokenLoader = opts.tokenLoader;
+    this.tokenSaver = opts.tokenSaver;
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────
+  async connect(config) {
+    this.config = config;
+    const scopes = config.scopes ?? [
+      "https://www.googleapis.com/auth/gmail.readonly"
+    ];
+    if (config.serviceAccount) {
+      this.client = await createServiceAccountClient(config.serviceAccount, scopes);
+    } else if (config.oauth) {
+      this.client = await createOAuth2Client(config.oauth);
+      if (!this.tokenLoader) {
+        throw new Error("tokenLoader required for OAuth2 flow");
+      }
+      this.tokens = await loadTokens(this.tokenLoader, config.account);
+      if (!this.tokens) {
+        throw new Error(
+          `No stored tokens for account ${config.account}. Complete the OAuth flow first.`
+        );
+      }
+      this.tokens = await refreshIfNeeded(
+        this.client,
+        this.tokens,
+        this.tokenSaver ? async (t) => saveTokens(this.tokenSaver, config.account, t) : void 0
+      );
+      this.client.setCredentials(this.tokens);
+    } else {
+      throw new Error("Either serviceAccount or oauth config is required");
+    }
+    const { google } = await import("googleapis");
+    this.gmail = google.gmail({ version: "v1", auth: this.client });
+  }
+  async disconnect() {
+    this.client = null;
+    this.gmail = null;
+    this.tokens = null;
+    this.config = null;
+  }
+  async healthCheck() {
+    try {
+      this.ensureConnected();
+      const res = await this.gmail.users.getProfile({ userId: "me" });
+      return { ok: true, account: res.data.emailAddress };
+    } catch (err) {
+      return { ok: false, error: errorMessage(err) };
+    }
+  }
+  // ── Auth ───────────────────────────────────────────────────────
+  async authenticate(codeProvider) {
+    if (!this.config) {
+      return { success: false, error: "Call connect() first to set config, or pass config and call authenticate() before connect()." };
+    }
+    try {
+      if (!this.config.oauth) {
+        return { success: false, error: "OAuth config required for browser-based authenticate(). Use serviceAccount for headless auth." };
+      }
+      if (!this.tokenSaver) {
+        return { success: false, error: "tokenSaver required for authenticate() flow." };
+      }
+      const client = await createOAuth2Client(this.config.oauth);
+      const scopes = this.config.scopes ?? [
+        "https://www.googleapis.com/auth/gmail.readonly",
+        "https://www.googleapis.com/auth/gmail.send"
+      ];
+      const authUrl = getAuthUrl(client, scopes);
+      const code = await codeProvider(authUrl);
+      const tokens = await exchangeCode(client, code);
+      await saveTokens(this.tokenSaver, this.config.account, tokens);
+      this.tokens = tokens;
+      this.client = client;
+      this.client.setCredentials(tokens);
+      const { google } = await import("googleapis");
+      this.gmail = google.gmail({ version: "v1", auth: this.client });
+      return { success: true, account: this.config.account };
+    } catch (err) {
+      return { success: false, error: errorMessage(err) };
+    }
+  }
+  // ── Sync ───────────────────────────────────────────────────────
+  async sync(options) {
+    this.ensureConnected();
+    if (options?.cursor) {
+      return this.syncIncremental(options.cursor, options.limit);
+    }
+    return this.syncFull(options);
+  }
+  /** Incremental sync using Gmail history API. */
+  async syncIncremental(startHistoryId, limit) {
+    const records = [];
+    const errors = [];
+    const seenIds = /* @__PURE__ */ new Set();
+    let pageToken;
+    let latestHistoryId = startHistoryId;
+    do {
+      const res = await this.gmail.users.history.list({
+        userId: "me",
+        startHistoryId,
+        historyTypes: ["messageAdded"],
+        ...pageToken ? { pageToken } : {}
+      });
+      latestHistoryId = res.data.historyId ?? latestHistoryId;
+      const histories = res.data.history ?? [];
+      for (const h of histories) {
+        for (const added of h.messagesAdded ?? []) {
+          const msgId = added.message?.id;
+          if (!msgId || seenIds.has(msgId)) continue;
+          seenIds.add(msgId);
+          try {
+            const record = await this.fetchMessage(msgId);
+            records.push(record);
+          } catch (err) {
+            errors.push({ id: msgId, error: errorMessage(err) });
+          }
+          if (limit && records.length >= limit) {
+            return { records, cursor: latestHistoryId, hasMore: true, errors };
+          }
+        }
+      }
+      pageToken = res.data.nextPageToken ?? void 0;
+    } while (pageToken);
+    return { records, cursor: latestHistoryId, hasMore: false, errors };
+  }
+  /** Full sync — list messages and fetch each one. */
+  async syncFull(options) {
+    const records = [];
+    const errors = [];
+    const maxResults = options?.limit ?? 100;
+    let query = "";
+    if (options?.since) {
+      const epoch = Math.floor(new Date(options.since).getTime() / 1e3);
+      query = `after:${epoch}`;
+    }
+    if (options?.filters?.q) {
+      query = query ? `${query} ${options.filters.q}` : String(options.filters.q);
+    }
+    let pageToken;
+    let collected = 0;
+    do {
+      const res = await this.gmail.users.messages.list({
+        userId: "me",
+        maxResults: Math.min(maxResults - collected, 100),
+        ...query ? { q: query } : {},
+        ...pageToken ? { pageToken } : {}
+      });
+      const messages = res.data.messages ?? [];
+      for (const msg of messages) {
+        try {
+          const record = await this.fetchMessage(msg.id);
+          records.push(record);
+        } catch (err) {
+          errors.push({ id: msg.id, error: errorMessage(err) });
+        }
+        collected++;
+        if (collected >= maxResults) break;
+      }
+      pageToken = res.data.nextPageToken ?? void 0;
+    } while (pageToken && collected < maxResults);
+    const profile = await this.gmail.users.getProfile({ userId: "me" });
+    const cursor = profile.data.historyId ?? void 0;
+    return {
+      records,
+      cursor,
+      hasMore: !!pageToken,
+      errors
+    };
+  }
+  // ── Push (send email) ─────────────────────────────────────────
+  async push(payload) {
+    this.ensureConnected();
+    try {
+      const toHeader = payload.to.map(formatAddress).join(", ");
+      const ccHeader = payload.cc.length ? `Cc: ${payload.cc.map(formatAddress).join(", ")}\r
+` : "";
+      const bccHeader = payload.bcc.length ? `Bcc: ${payload.bcc.map(formatAddress).join(", ")}\r
+` : "";
+      const mime = [
+        `To: ${toHeader}\r
+`,
+        ccHeader,
+        bccHeader,
+        `Subject: ${payload.subject}\r
+`,
+        `Content-Type: text/plain; charset="UTF-8"\r
+`,
+        `\r
+`,
+        payload.body ?? ""
+      ].join("");
+      const encoded = Buffer.from(mime).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+      const res = await this.gmail.users.messages.send({
+        userId: "me",
+        requestBody: { raw: encoded }
+      });
+      return { success: true, externalId: res.data.id };
+    } catch (err) {
+      return { success: false, error: errorMessage(err) };
+    }
+  }
+  // ── Internals ─────────────────────────────────────────────────
+  ensureConnected() {
+    if (!this.gmail || !this.config) {
+      throw new Error("GoogleGmailConnector is not connected. Call connect() first.");
+    }
+  }
+  /** Fetch a single message by ID and parse into an EmailRecord. */
+  async fetchMessage(messageId) {
+    const res = await this.gmail.users.messages.get({
+      userId: "me",
+      id: messageId,
+      format: "metadata",
+      metadataHeaders: ["From", "To", "Cc", "Bcc", "Subject", "Date"]
+    });
+    const msg = res.data;
+    const headers = msg.payload?.headers ?? [];
+    const getHeader = (name) => headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+    return {
+      gmailId: msg.id,
+      threadId: msg.threadId,
+      account: this.config.account,
+      subject: getHeader("Subject"),
+      from: parseAddress(getHeader("From")),
+      to: parseAddressList(getHeader("To")),
+      cc: parseAddressList(getHeader("Cc")),
+      bcc: parseAddressList(getHeader("Bcc")),
+      date: new Date(getHeader("Date")).toISOString(),
+      snippet: msg.snippet ?? "",
+      labels: msg.labelIds ?? [],
+      isRead: !(msg.labelIds ?? []).includes("UNREAD")
+    };
+  }
+};
+function parseAddress(raw) {
+  const match = raw.match(/^(.+?)\s*<([^>]+)>$/);
+  if (match) {
+    return { name: match[1].replace(/^["']|["']$/g, "").trim(), email: match[2] };
+  }
+  return { email: raw.trim() };
+}
+function parseAddressList(raw) {
+  if (!raw.trim()) return [];
+  const results = [];
+  const parts = raw.split(/,(?=(?:[^<]*<[^>]*>)*[^>]*$)/);
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed) results.push(parseAddress(trimmed));
+  }
+  return results;
+}
+function formatAddress(addr) {
+  return addr.name ? `${addr.name} <${addr.email}>` : addr.email;
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export {
+  createOAuth2Client,
+  getAuthUrl,
+  exchangeCode,
+  createServiceAccountClient,
+  loadTokens,
+  saveTokens,
+  refreshIfNeeded,
+  GoogleGmailConnector
+};

package/dist/chunk-D47AIFOD.js

@@ -0,0 +1,351 @@
+// src/connectors/google/oauth.ts
+var _google;
+async function getGoogle() {
+  if (!_google) {
+    try {
+      const mod = await import("googleapis");
+      _google = mod.google;
+    } catch {
+      throw new Error(
+        "googleapis is required for Google connectors. Install it: npm install googleapis"
+      );
+    }
+  }
+  return _google;
+}
+async function createOAuth2Client(config) {
+  const google = await getGoogle();
+  return new google.auth.OAuth2(
+    config.clientId,
+    config.clientSecret,
+    config.redirectUri
+  );
+}
+function getAuthUrl(client, scopes) {
+  return client.generateAuthUrl({
+    access_type: "offline",
+    prompt: "consent",
+    scope: scopes
+  });
+}
+async function exchangeCode(client, code) {
+  const { tokens } = await client.getToken(code);
+  return tokens;
+}
+async function createServiceAccountClient(config, scopes) {
+  const google = await getGoogle();
+  const auth = new google.auth.GoogleAuth({
+    ...config.keyFile ? { keyFile: config.keyFile } : {},
+    ...config.credentials ? { credentials: config.credentials } : {},
+    scopes,
+    clientOptions: { subject: config.subject }
+  });
+  return auth.getClient();
+}
+async function loadTokens(getter, accountKey) {
+  const raw = await getter(`google_tokens:${accountKey}`);
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function saveTokens(setter, accountKey, tokens) {
+  await setter(`google_tokens:${accountKey}`, JSON.stringify(tokens));
+}
+async function refreshIfNeeded(client, tokens, saver) {
+  const buffer = 6e4;
+  const isExpired = tokens.expiry_date != null && Date.now() >= tokens.expiry_date - buffer;
+  if (!isExpired) return tokens;
+  client.setCredentials(tokens);
+  const { credentials } = await client.refreshAccessToken();
+  const refreshed = {
+    access_token: credentials.access_token,
+    refresh_token: credentials.refresh_token ?? tokens.refresh_token,
+    expiry_date: credentials.expiry_date ?? void 0,
+    token_type: credentials.token_type ?? "Bearer"
+  };
+  if (saver) {
+    await saver(refreshed);
+  }
+  return refreshed;
+}
+
+// src/connectors/google/gmail-connector.ts
+var GoogleGmailConnector = class {
+  id = "google-gmail";
+  meta = {
+    displayName: "Google Gmail",
+    provider: "google",
+    dataType: "email"
+  };
+  tokenLoader;
+  tokenSaver;
+  client = null;
+  config = null;
+  tokens = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  gmail = null;
+  constructor(opts = {}) {
+    this.tokenLoader = opts.tokenLoader;
+    this.tokenSaver = opts.tokenSaver;
+  }
+  // ── Lifecycle ──────────────────────────────────────────────────
+  async connect(config) {
+    this.config = config;
+    const scopes = config.scopes ?? [
+      "https://www.googleapis.com/auth/gmail.readonly"
+    ];
+    if (config.serviceAccount) {
+      this.client = await createServiceAccountClient(config.serviceAccount, scopes);
+    } else if (config.oauth) {
+      this.client = await createOAuth2Client(config.oauth);
+      if (!this.tokenLoader) {
+        throw new Error("tokenLoader required for OAuth2 flow");
+      }
+      this.tokens = await loadTokens(this.tokenLoader, config.account);
+      if (!this.tokens) {
+        throw new Error(
+          `No stored tokens for account ${config.account}. Complete the OAuth flow first.`
+        );
+      }
+      this.tokens = await refreshIfNeeded(
+        this.client,
+        this.tokens,
+        this.tokenSaver ? async (t) => saveTokens(this.tokenSaver, config.account, t) : void 0
+      );
+      this.client.setCredentials(this.tokens);
+    } else {
+      throw new Error("Either serviceAccount or oauth config is required");
+    }
+    const { google } = await import("googleapis");
+    this.gmail = google.gmail({ version: "v1", auth: this.client });
+  }
+  async disconnect() {
+    this.client = null;
+    this.gmail = null;
+    this.tokens = null;
+    this.config = null;
+  }
+  async healthCheck() {
+    try {
+      this.ensureConnected();
+      const res = await this.gmail.users.getProfile({ userId: "me" });
+      return { ok: true, account: res.data.emailAddress };
+    } catch (err) {
+      return { ok: false, error: errorMessage(err) };
+    }
+  }
+  // ── Auth ───────────────────────────────────────────────────────
+  async authenticate(codeProvider) {
+    if (!this.config) {
+      return { success: false, error: "Call connect() first to set config, or pass config and call authenticate() before connect()." };
+    }
+    try {
+      const client = await createOAuth2Client(this.config.oauth);
+      const scopes = this.config.scopes ?? [
+        "https://www.googleapis.com/auth/gmail.readonly",
+        "https://www.googleapis.com/auth/gmail.send"
+      ];
+      const authUrl = getAuthUrl(client, scopes);
+      const code = await codeProvider(authUrl);
+      const tokens = await exchangeCode(client, code);
+      await saveTokens(this.tokenSaver, this.config.account, tokens);
+      this.tokens = tokens;
+      this.client = client;
+      this.client.setCredentials(tokens);
+      const { google } = await import("googleapis");
+      this.gmail = google.gmail({ version: "v1", auth: this.client });
+      return { success: true, account: this.config.account };
+    } catch (err) {
+      return { success: false, error: errorMessage(err) };
+    }
+  }
+  // ── Sync ───────────────────────────────────────────────────────
+  async sync(options) {
+    this.ensureConnected();
+    if (options?.cursor) {
+      return this.syncIncremental(options.cursor, options.limit);
+    }
+    return this.syncFull(options);
+  }
+  /** Incremental sync using Gmail history API. */
+  async syncIncremental(startHistoryId, limit) {
+    const records = [];
+    const errors = [];
+    const seenIds = /* @__PURE__ */ new Set();
+    let pageToken;
+    let latestHistoryId = startHistoryId;
+    do {
+      const res = await this.gmail.users.history.list({
+        userId: "me",
+        startHistoryId,
+        historyTypes: ["messageAdded"],
+        ...pageToken ? { pageToken } : {}
+      });
+      latestHistoryId = res.data.historyId ?? latestHistoryId;
+      const histories = res.data.history ?? [];
+      for (const h of histories) {
+        for (const added of h.messagesAdded ?? []) {
+          const msgId = added.message?.id;
+          if (!msgId || seenIds.has(msgId)) continue;
+          seenIds.add(msgId);
+          try {
+            const record = await this.fetchMessage(msgId);
+            records.push(record);
+          } catch (err) {
+            errors.push({ id: msgId, error: errorMessage(err) });
+          }
+          if (limit && records.length >= limit) {
+            return { records, cursor: latestHistoryId, hasMore: true, errors };
+          }
+        }
+      }
+      pageToken = res.data.nextPageToken ?? void 0;
+    } while (pageToken);
+    return { records, cursor: latestHistoryId, hasMore: false, errors };
+  }
+  /** Full sync — list messages and fetch each one. */
+  async syncFull(options) {
+    const records = [];
+    const errors = [];
+    const maxResults = options?.limit ?? 100;
+    let query = "";
+    if (options?.since) {
+      const epoch = Math.floor(new Date(options.since).getTime() / 1e3);
+      query = `after:${epoch}`;
+    }
+    if (options?.filters?.q) {
+      query = query ? `${query} ${options.filters.q}` : String(options.filters.q);
+    }
+    let pageToken;
+    let collected = 0;
+    do {
+      const res = await this.gmail.users.messages.list({
+        userId: "me",
+        maxResults: Math.min(maxResults - collected, 100),
+        ...query ? { q: query } : {},
+        ...pageToken ? { pageToken } : {}
+      });
+      const messages = res.data.messages ?? [];
+      for (const msg of messages) {
+        try {
+          const record = await this.fetchMessage(msg.id);
+          records.push(record);
+        } catch (err) {
+          errors.push({ id: msg.id, error: errorMessage(err) });
+        }
+        collected++;
+        if (collected >= maxResults) break;
+      }
+      pageToken = res.data.nextPageToken ?? void 0;
+    } while (pageToken && collected < maxResults);
+    const profile = await this.gmail.users.getProfile({ userId: "me" });
+    const cursor = profile.data.historyId ?? void 0;
+    return {
+      records,
+      cursor,
+      hasMore: !!pageToken,
+      errors
+    };
+  }
+  // ── Push (send email) ─────────────────────────────────────────
+  async push(payload) {
+    this.ensureConnected();
+    try {
+      const toHeader = payload.to.map(formatAddress).join(", ");
+      const ccHeader = payload.cc.length ? `Cc: ${payload.cc.map(formatAddress).join(", ")}\r
+` : "";
+      const bccHeader = payload.bcc.length ? `Bcc: ${payload.bcc.map(formatAddress).join(", ")}\r
+` : "";
+      const mime = [
+        `To: ${toHeader}\r
+`,
+        ccHeader,
+        bccHeader,
+        `Subject: ${payload.subject}\r
+`,
+        `Content-Type: text/plain; charset="UTF-8"\r
+`,
+        `\r
+`,
+        payload.body ?? ""
+      ].join("");
+      const encoded = Buffer.from(mime).toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+      const res = await this.gmail.users.messages.send({
+        userId: "me",
+        requestBody: { raw: encoded }
+      });
+      return { success: true, externalId: res.data.id };
+    } catch (err) {
+      return { success: false, error: errorMessage(err) };
+    }
+  }
+  // ── Internals ─────────────────────────────────────────────────
+  ensureConnected() {
+    if (!this.gmail || !this.config) {
+      throw new Error("GoogleGmailConnector is not connected. Call connect() first.");
+    }
+  }
+  /** Fetch a single message by ID and parse into an EmailRecord. */
+  async fetchMessage(messageId) {
+    const res = await this.gmail.users.messages.get({
+      userId: "me",
+      id: messageId,
+      format: "metadata",
+      metadataHeaders: ["From", "To", "Cc", "Bcc", "Subject", "Date"]
+    });
+    const msg = res.data;
+    const headers = msg.payload?.headers ?? [];
+    const getHeader = (name) => headers.find((h) => h.name.toLowerCase() === name.toLowerCase())?.value ?? "";
+    return {
+      gmailId: msg.id,
+      threadId: msg.threadId,
+      account: this.config.account,
+      subject: getHeader("Subject"),
+      from: parseAddress(getHeader("From")),
+      to: parseAddressList(getHeader("To")),
+      cc: parseAddressList(getHeader("Cc")),
+      bcc: parseAddressList(getHeader("Bcc")),
+      date: new Date(getHeader("Date")).toISOString(),
+      snippet: msg.snippet ?? "",
+      labels: msg.labelIds ?? [],
+      isRead: !(msg.labelIds ?? []).includes("UNREAD")
+    };
+  }
+};
+function parseAddress(raw) {
+  const match = raw.match(/^(.+?)\s*<([^>]+)>$/);
+  if (match) {
+    return { name: match[1].replace(/^["']|["']$/g, "").trim(), email: match[2] };
+  }
+  return { email: raw.trim() };
+}
+function parseAddressList(raw) {
+  if (!raw.trim()) return [];
+  const results = [];
+  const parts = raw.split(/,(?=(?:[^<]*<[^>]*>)*[^>]*$)/);
+  for (const part of parts) {
+    const trimmed = part.trim();
+    if (trimmed) results.push(parseAddress(trimmed));
+  }
+  return results;
+}
+function formatAddress(addr) {
+  return addr.name ? `${addr.name} <${addr.email}>` : addr.email;
+}
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+export {
+  createOAuth2Client,
+  getAuthUrl,
+  exchangeCode,
+  createServiceAccountClient,
+  loadTokens,
+  saveTokens,
+  refreshIfNeeded,
+  GoogleGmailConnector
+};

package/dist/cli.js

@@ -3,13 +3,88 @@
 // src/cli.ts
 import * as readline from "readline";
 import * as fs from "fs";
+import { execSync } from "child_process";
+
+// src/update-check.ts
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+var ONE_DAY_MS = 864e5;
+function isNewer(latest, current) {
+  const a = latest.split(".").map(Number);
+  const b = current.split(".").map(Number);
+  for (let i = 0; i < Math.max(a.length, b.length); i++) {
+    const av = a[i] ?? 0;
+    const bv = b[i] ?? 0;
+    if (av > bv) return true;
+    if (av < bv) return false;
+  }
+  return false;
+}
+async function checkForUpdate(pkgName, currentVersion) {
+  const cacheDir = join(homedir(), `.${pkgName}`);
+  const cachePath = join(cacheDir, "update-check.json");
+  try {
+    if (existsSync(cachePath)) {
+      const cached = JSON.parse(readFileSync(cachePath, "utf-8"));
+      if (Date.now() - cached.checked < ONE_DAY_MS) {
+        return isNewer(cached.latest, currentVersion) ? cached.latest : null;
+      }
+    }
+  } catch {
+  }
+  const res = await fetch(`https://registry.npmjs.org/${pkgName}/latest`, {
+    headers: { accept: "application/json" },
+    signal: AbortSignal.timeout(5e3)
+  });
+  if (!res.ok) return null;
+  const data = await res.json();
+  const latest = data.version;
+  try {
+    if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
+    writeFileSync(cachePath, JSON.stringify({ latest, checked: Date.now() }));
+  } catch {
+  }
+  return isNewer(latest, currentVersion) ? latest : null;
+}
+
+// src/cli.ts
+function getVersion() {
+  try {
+    const pkgPath = new URL("../package.json", import.meta.url).pathname;
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
+    return pkg.version;
+  } catch {
+    return "unknown";
+  }
+}
 async function main(args) {
   const [command, subcommand, ...rest] = args;
-  if (command === "auth" && subcommand === "google") {
+  const version = getVersion();
+  if (version !== "unknown") {
+    checkForUpdate("botinabox", version).then((latest) => {
+      if (latest) {
+        process.on("exit", () => {
+          console.log(
+            `
+Update available: ${version} \u2192 ${latest} \u2014 run "botinabox update" to upgrade`
+          );
+        });
+      }
+    }).catch(() => {
+    });
+  }
+  if (command === "update") {
+    await runUpdate(version);
+  } else if (command === "--version" || command === "-v") {
+    console.log(version);
+  } else if (command === "auth" && subcommand === "google") {
     await authGoogle(rest);
   } else {
     console.log("Usage:");
     console.log("  botinabox auth google <account-email> [options]");
+    console.log("  botinabox update                              Upgrade to the latest version");
+    console.log("  botinabox --version                           Print version");
     console.log("");
     console.log("Options:");
     console.log("  --client-id=<id>           Google OAuth client ID");
@@ -20,6 +95,22 @@ async function main(args) {
     process.exit(1);
   }
 }
+async function runUpdate(currentVersion) {
+  console.log(`Current version: ${currentVersion}`);
+  const latest = await checkForUpdate("botinabox", currentVersion);
+  if (!latest) {
+    console.log("Already up to date.");
+    return;
+  }
+  console.log(`Updating to ${latest}...`);
+  try {
+    execSync("npm install -g botinabox@latest", { stdio: "inherit" });
+    console.log(`Updated botinabox ${currentVersion} \u2192 ${latest}`);
+  } catch {
+    console.error("Update failed. Try running manually: npm install -g botinabox@latest");
+    process.exit(1);
+  }
+}
 async function authGoogle(args) {
   const flags = /* @__PURE__ */ new Map();
   let account;
@@ -87,7 +178,7 @@ async function authGoogle(args) {
       });
     }
   };
-  const { GoogleGmailConnector } = await import("./gmail-connector-2FVYTQJH.js");
+  const { GoogleGmailConnector } = await import("./gmail-connector-MNUBRNFM.js");
   const connector = new GoogleGmailConnector({ tokenLoader, tokenSaver });
   connector.config = {
     account,

package/dist/connectors/google/index.d.ts

@@ -13,11 +13,26 @@ interface GoogleTokens {
     expiry_date?: number;
     token_type: string;
 }
+interface GoogleServiceAccountConfig {
+    /** Path to service account key JSON file */
+    keyFile?: string;
+    /** Inline service account credentials (alternative to keyFile) */
+    credentials?: {
+        client_email: string;
+        private_key: string;
+        project_id?: string;
+    };
+    /** Email of the user to impersonate via domain-wide delegation */
+    subject: string;
+}
 interface GoogleConnectorConfig extends ConnectorConfig {
     /** Google account email */
     account: string;
-    oauth: GoogleOAuthConfig;
-    scopes: string[];
+    /** OAuth2 user auth (requires browser flow) */
+    oauth?: GoogleOAuthConfig;
+    /** Service account auth (headless, for cloud deployments) */
+    serviceAccount?: GoogleServiceAccountConfig;
+    scopes?: string[];
 }
 interface EmailAddress {
     name?: string;
@@ -84,6 +99,11 @@ declare function getAuthUrl(client: OAuth2Client, scopes: string[]): string;
  * Exchange an authorization code for tokens.
  */
 declare function exchangeCode(client: OAuth2Client, code: string): Promise<GoogleTokens>;
+/**
+ * Create an authenticated client using a service account with
+ * domain-wide delegation (impersonation). No browser flow needed.
+ */
+declare function createServiceAccountClient(config: GoogleServiceAccountConfig, scopes: string[]): Promise<OAuth2Client>;
 /**
  * Load persisted tokens via a generic getter callback.
  *
@@ -115,21 +135,21 @@ declare function refreshIfNeeded(client: OAuth2Client, tokens: GoogleTokens, sav
  */
 
 interface GmailConnectorOpts {
-    /** Load persisted tokens for a given account key. */
-    tokenLoader: (key: string) => Promise<string | null>;
-    /** Persist tokens for a given account key. */
-    tokenSaver: (key: string, value: string) => Promise<void>;
+    /** Load persisted tokens for a given account key (OAuth2 flow only). */
+    tokenLoader?: (key: string) => Promise<string | null>;
+    /** Persist tokens for a given account key (OAuth2 flow only). */
+    tokenSaver?: (key: string, value: string) => Promise<void>;
 }
 declare class GoogleGmailConnector implements Connector<EmailRecord> {
     readonly id = "google-gmail";
     readonly meta: ConnectorMeta;
-    private tokenLoader;
-    private tokenSaver;
+    private tokenLoader?;
+    private tokenSaver?;
     private client;
     private config;
     private tokens;
     private gmail;
-    constructor(opts: GmailConnectorOpts);
+    constructor(opts?: GmailConnectorOpts);
     connect(config: GoogleConnectorConfig): Promise<void>;
     disconnect(): Promise<void>;
     healthCheck(): Promise<{
@@ -157,21 +177,21 @@ declare class GoogleGmailConnector implements Connector<EmailRecord> {
  */
 
 interface CalendarConnectorOpts {
-    /** Load persisted tokens for a given account key. */
-    tokenLoader: (key: string) => Promise<string | null>;
-    /** Persist tokens for a given account key. */
-    tokenSaver: (key: string, value: string) => Promise<void>;
+    /** Load persisted tokens for a given account key (OAuth2 flow only). */
+    tokenLoader?: (key: string) => Promise<string | null>;
+    /** Persist tokens for a given account key (OAuth2 flow only). */
+    tokenSaver?: (key: string, value: string) => Promise<void>;
 }
 declare class GoogleCalendarConnector implements Connector<CalendarEventRecord> {
     readonly id = "google-calendar";
     readonly meta: ConnectorMeta;
-    private tokenLoader;
-    private tokenSaver;
+    private tokenLoader?;
+    private tokenSaver?;
     private client;
     private config;
     private tokens;
     private calendar;
-    constructor(opts: CalendarConnectorOpts);
+    constructor(opts?: CalendarConnectorOpts);
     connect(config: GoogleConnectorConfig): Promise<void>;
     disconnect(): Promise<void>;
     healthCheck(): Promise<{
@@ -189,4 +209,4 @@ declare class GoogleCalendarConnector implements Connector<CalendarEventRecord>
     private mapEvent;
 }
 
-export { type CalendarAttendee, type CalendarConnectorOpts, type CalendarEventRecord, type EmailAddress, type EmailRecord, type GmailConnectorOpts, GoogleCalendarConnector, type GoogleConnectorConfig, GoogleGmailConnector, type GoogleOAuthConfig, type GoogleTokens, createOAuth2Client, exchangeCode, getAuthUrl, loadTokens, refreshIfNeeded, saveTokens };
+export { type CalendarAttendee, type CalendarConnectorOpts, type CalendarEventRecord, type EmailAddress, type EmailRecord, type GmailConnectorOpts, GoogleCalendarConnector, type GoogleConnectorConfig, GoogleGmailConnector, type GoogleOAuthConfig, type GoogleServiceAccountConfig, type GoogleTokens, createOAuth2Client, createServiceAccountClient, exchangeCode, getAuthUrl, loadTokens, refreshIfNeeded, saveTokens };

package/dist/connectors/google/index.js

@@ -1,12 +1,13 @@
 import {
   GoogleGmailConnector,
   createOAuth2Client,
+  createServiceAccountClient,
   exchangeCode,
   getAuthUrl,
   loadTokens,
   refreshIfNeeded,
   saveTokens
-} from "../../chunk-DSNJKNEW.js";
+} from "../../chunk-3X3YKI4T.js";
 
 // src/connectors/google/calendar-connector.ts
 var GoogleCalendarConnector = class {
@@ -23,26 +24,38 @@ var GoogleCalendarConnector = class {
   tokens = null;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   calendar = null;
-  constructor(opts) {
+  constructor(opts = {}) {
     this.tokenLoader = opts.tokenLoader;
     this.tokenSaver = opts.tokenSaver;
   }
   // ── Lifecycle ──────────────────────────────────────────────────
   async connect(config) {
     this.config = config;
-    this.client = await createOAuth2Client(config.oauth);
-    this.tokens = await loadTokens(this.tokenLoader, config.account);
-    if (!this.tokens) {
-      throw new Error(
-        `No stored tokens for account ${config.account}. Complete the OAuth flow first.`
+    const scopes = config.scopes ?? [
+      "https://www.googleapis.com/auth/calendar.readonly"
+    ];
+    if (config.serviceAccount) {
+      this.client = await createServiceAccountClient(config.serviceAccount, scopes);
+    } else if (config.oauth) {
+      this.client = await createOAuth2Client(config.oauth);
+      if (!this.tokenLoader) {
+        throw new Error("tokenLoader required for OAuth2 flow");
+      }
+      this.tokens = await loadTokens(this.tokenLoader, config.account);
+      if (!this.tokens) {
+        throw new Error(
+          `No stored tokens for account ${config.account}. Complete the OAuth flow first.`
+        );
+      }
+      this.tokens = await refreshIfNeeded(
+        this.client,
+        this.tokens,
+        this.tokenSaver ? async (t) => saveTokens(this.tokenSaver, config.account, t) : void 0
       );
+      this.client.setCredentials(this.tokens);
+    } else {
+      throw new Error("Either serviceAccount or oauth config is required");
     }
-    this.tokens = await refreshIfNeeded(
-      this.client,
-      this.tokens,
-      async (t) => saveTokens(this.tokenSaver, config.account, t)
-    );
-    this.client.setCredentials(this.tokens);
     const { google } = await import("googleapis");
     this.calendar = google.calendar({ version: "v3", auth: this.client });
   }
@@ -71,6 +84,12 @@ var GoogleCalendarConnector = class {
       return { success: false, error: "Call connect() first to set config, or pass config and call authenticate() before connect()." };
     }
     try {
+      if (!this.config.oauth) {
+        return { success: false, error: "OAuth config required for browser-based authenticate(). Use serviceAccount for headless auth." };
+      }
+      if (!this.tokenSaver) {
+        return { success: false, error: "tokenSaver required for authenticate() flow." };
+      }
       const client = await createOAuth2Client(this.config.oauth);
       const scopes = this.config.scopes ?? [
         "https://www.googleapis.com/auth/calendar.readonly"
@@ -219,6 +238,7 @@ export {
   GoogleCalendarConnector,
   GoogleGmailConnector,
   createOAuth2Client,
+  createServiceAccountClient,
   exchangeCode,
   getAuthUrl,
   loadTokens,

package/dist/gmail-connector-MNUBRNFM.js

@@ -0,0 +1,6 @@
+import {
+  GoogleGmailConnector
+} from "./chunk-3X3YKI4T.js";
+export {
+  GoogleGmailConnector
+};

package/dist/gmail-connector-URRFX6A3.js

@@ -0,0 +1,6 @@
+import {
+  GoogleGmailConnector
+} from "./chunk-D47AIFOD.js";
+export {
+  GoogleGmailConnector
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",
@@ -42,10 +42,18 @@
   "bin": {
     "botinabox": "./bin/botinabox.mjs"
   },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "scripts": {
     "build": "tsup",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build && npm run typecheck && npm test"
   },
   "dependencies": {
     "@types/uuid": "^10.0.0",

package/CHANGELOG.md

@@ -1,76 +0,0 @@
-# Changelog
-
-All notable changes to `botinabox` are documented here.
-
-Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [SemVer](https://semver.org/).
-
----
-
-## [0.5.2] — 2026-04-04
-
-### Added
-
-- **`authenticate()` method on Connector interface** — optional method for connectors that require OAuth or other auth flows. Accepts a `codeProvider` callback for interactive or programmatic authorization.
-- **Google connectors implement `authenticate()`** — `GoogleGmailConnector` and `GoogleCalendarConnector` now support self-authentication: generate consent URL, exchange code for tokens, persist via tokenSaver callback.
-- **`botinabox auth google` CLI** — native CLI command for Google OAuth setup: `botinabox auth google <account-email> --client-id=... --client-secret=...`. Stores tokens in the secrets table.
-
-## [0.5.1] — 2026-04-04
-
-### Fixed
-
-- **cron-parser ESM import** — cron-parser v4 is CommonJS-only; fixed named import to default import (`import cronParser from "cron-parser"`).
-
-## [0.5.0] — 2026-04-04
-
-### Added
-
-- **Connector interface** — Generic `Connector<T>` abstraction for external service integrations (Gmail, Calendar, Trello, Jira, Salesforce, etc.). Pull-based `sync()` returns typed records; optional `push()` writes back. Connectors produce data — consumers decide where to store it. New `connectors` config key in `BotConfig`.
-- **Google connectors** — `GoogleGmailConnector` and `GoogleCalendarConnector` implementing `Connector<EmailRecord>` and `Connector<CalendarEventRecord>`. Incremental sync (Gmail historyId, Calendar syncToken), full sync with pagination, email sending via `push()`. OAuth2 helpers with callback-based token persistence. Exported from `botinabox/google`. `googleapis` as optional peer dependency.
-- **Scheduler** — Database-backed `Scheduler` class with `schedules` core table. Supports recurring (cron expressions via `cron-parser`) and one-time schedules. Hook-based actions: when a schedule fires, it emits the configured action as a hook event. Methods: `register()`, `update()`, `unregister()`, `list()`, `tick()`.
-- **`schedules` core table** — id, name, type (recurring/one_time), cron, run_at, timezone, enabled, action, action_config, last_fired_at, next_fire_at.
-
-### Deprecated
-
-- **HeartbeatScheduler** — Replaced by `Scheduler`. HeartbeatScheduler uses in-memory `setInterval` which loses state on restart. Kept for backward compatibility but marked `@deprecated`.
-
-### Dependencies
-
-- Added `cron-parser` ^4.9.0.
-- Added `googleapis` >=140.0.0 as optional peer dependency.
-
-## [0.3.0] — 2026-04-03
-
-### Added
-
-- **Domain tables** — `defineDomainTables(db, options?)` creates standard multi-agent app tables: org, project, client, invoice, repository, file, channel, rule, event + junction tables. Configurable: disable clients, repos, files, channels, rules, or events.
-- **Domain entity contexts** — `defineDomainEntityContexts(db, options?)` renders per-entity context directories for all domain tables. Projects get REPOS.md + RULES.md. Clients get REPOS.md + AGENTS.md + INVOICES.md.
-- **Claude stream parser** — `parseClaudeStream(stdout)` parses Claude CLI NDJSON output into structured results (session, model, cost, tokens, text, errors). Plus `isMaxTurns()`, `isLoginRequired()`, `deactivateLocalImagePaths()`.
-- **Process env builder** — `buildProcessEnv(allowedKeys?, inject?)` creates a clean subprocess environment with only safe variables. Strips all secrets.
-
-## [0.2.0] — 2026-04-03
-
-### Added
-
-- **Users primitive** — `users` and `user_identities` core tables. Users are protected objects (never auto-rendered into other entities' context). `UserRegistry` class: `register()`, `getById()`, `getByEmail()`, `resolveByIdentity()`, `resolveOrCreate()`, `addIdentity()`.
-- **Secrets primitive** — `secrets` core table for encrypted credential storage. Protected by default. `SecretStore` class: `set()`, `get()`, `getMeta()`, `list()`, `rotate()`, `delete()`.
-- **Message pipeline user resolution** — `MessagePipeline` accepts optional `UserRegistry`. When provided, resolves `InboundMessage.from` to a user ID via `resolveOrCreate()` before task creation. `InboundMessage.userId` field added.
-- **`user_id` on messages table** — Tracks resolved user alongside raw `peer_id`.
-- **Protected/encrypted passthrough** — `EntityContextDef` now supports `protected` and `encrypted` fields, passed through to Lattice's entity context system.
-
-### Changed
-
-- Core table count: 15 → 18 (added `users`, `user_identities`, `secrets`).
-- `messages` table gains `user_id` column.
-
-## [0.1.1] — 2026-03-28
-
-### Fixed
-
-- Initial release bug fixes and stability improvements.
-
-## [0.1.0] — 2026-03-25
-
-### Added
-
-- Initial release: DataStore, HookBus, AgentRegistry, TaskQueue, RunManager, WakeupQueue, BudgetController, WorkflowEngine, SessionManager, ChannelRegistry, MessagePipeline.
-- 15 core tables, LLM provider routing, channel adapters (Slack, Discord, Webhook).

package/CONTRIBUTING.md

@@ -1,92 +0,0 @@
-# Contributing
-
-Thanks for your interest in contributing to Bot in a Box.
-
-## Development Setup
-
-```bash
-git clone https://github.com/automated-industries/botinabox.git
-cd botinabox
-pnpm install
-pnpm build
-```
-
-## Project Structure
-
-This is a pnpm monorepo. Packages are in `packages/`:
-
-- `shared/` — Types and constants (zero dependencies)
-- `core/` — Core framework
-- `cli/` — CLI scaffolding tool
-- `providers/` — LLM provider adapters
-- `channels/` — Messaging channel adapters
-
-## Running Tests
-
-```bash
-# All packages
-pnpm test:run
-
-# Single package
-cd packages/core && pnpm test
-```
-
-Tests use [Vitest](https://vitest.dev/). Each package has its own `vitest.config.ts`.
-
-## Building
-
-```bash
-# All packages
-pnpm build
-
-# Single package
-cd packages/core && pnpm build
-```
-
-Build uses [tsup](https://tsup.egoist.dev/) targeting ESM with declaration files.
-
-## Type Checking
-
-```bash
-pnpm typecheck
-```
-
-## Code Style
-
-- TypeScript with strict mode
-- ESM modules (`"type": "module"`)
-- ES2022 target
-- No default exports except for provider/channel factory functions
-
-## Making Changes
-
-1. Create a branch from `main`
-2. Make your changes
-3. Add or update tests
-4. Run `pnpm test:run` and `pnpm typecheck`
-5. Open a pull request
-
-## Adding a Provider
-
-1. Create `packages/providers/your-provider/`
-2. Implement the `LLMProvider` interface from `@botinabox/shared`
-3. Export a default factory function
-4. Add `"botinabox": { "type": "provider" }` to `package.json`
-5. Add tests
-
-## Adding a Channel Adapter
-
-1. Create `packages/channels/your-channel/`
-2. Implement the `ChannelAdapter` interface from `@botinabox/shared`
-3. Export a default factory function
-4. Add `"botinabox": { "type": "channel" }` to `package.json`
-5. Add tests
-
-## Reporting Issues
-
-Open an issue on GitHub with:
-
-- Steps to reproduce
-- Expected behavior
-- Actual behavior
-- Node.js and pnpm versions