botinabox 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,24 @@ Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Versioning: [S
 
 ---
 
+## [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

package/dist/connector-DDahQw-2.d.ts

@@ -0,0 +1,63 @@
+/** Connector types — generic external service integrations. */
+interface ConnectorMeta {
+    displayName: string;
+    /** Provider identifier, e.g. "google", "trello", "jira", "salesforce" */
+    provider: string;
+    /** Data type this connector handles, e.g. "email", "calendar", "board", "crm" */
+    dataType: string;
+}
+interface SyncOptions {
+    /** Only sync records after this ISO 8601 timestamp */
+    since?: string;
+    /** Provider-specific incremental sync token */
+    cursor?: string;
+    /** Maximum number of records to fetch */
+    limit?: number;
+    /** Provider-specific query filters */
+    filters?: Record<string, unknown>;
+}
+interface SyncResult<T = Record<string, unknown>> {
+    /** Typed records produced by the connector — consumer decides where to store */
+    records: T[];
+    /** Next incremental sync token (persist for future calls) */
+    cursor?: string;
+    /** Whether more records are available (pagination) */
+    hasMore: boolean;
+    /** Errors encountered during sync (non-fatal per-record failures) */
+    errors: Array<{
+        id?: string;
+        error: string;
+    }>;
+}
+interface PushResult {
+    success: boolean;
+    externalId?: string;
+    error?: string;
+}
+type ConnectorConfig = Record<string, unknown>;
+/**
+ * Generic connector interface for external service integrations.
+ *
+ * Connectors pull and optionally push data to/from external services
+ * (Gmail, Calendar, Trello, Jira, Salesforce, etc.). They produce
+ * typed records — the consuming application decides where to store them.
+ *
+ * @typeParam T - The record type this connector produces/consumes.
+ */
+interface Connector<T = Record<string, unknown>> {
+    readonly id: string;
+    readonly meta: ConnectorMeta;
+    connect(config: ConnectorConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        account?: string;
+        error?: string;
+    }>;
+    /** Pull records from external source */
+    sync(options?: SyncOptions): Promise<SyncResult<T>>;
+    /** Push a record to external source (optional) */
+    push?(payload: T): Promise<PushResult>;
+}
+
+export type { ConnectorConfig as C, PushResult as P, SyncOptions as S, Connector as a, ConnectorMeta as b, SyncResult as c };

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

@@ -0,0 +1,190 @@
+import { C as ConnectorConfig, a as Connector, b as ConnectorMeta, S as SyncOptions, c as SyncResult, P as PushResult } from '../../connector-DDahQw-2.js';
+
+/** Google connector types. */
+
+interface GoogleOAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+interface GoogleTokens {
+    access_token: string;
+    refresh_token?: string;
+    expiry_date?: number;
+    token_type: string;
+}
+interface GoogleConnectorConfig extends ConnectorConfig {
+    /** Google account email */
+    account: string;
+    oauth: GoogleOAuthConfig;
+    scopes: string[];
+}
+interface EmailAddress {
+    name?: string;
+    email: string;
+}
+interface EmailRecord {
+    gmailId: string;
+    threadId: string;
+    account: string;
+    subject: string;
+    from: EmailAddress;
+    to: EmailAddress[];
+    cc: EmailAddress[];
+    bcc: EmailAddress[];
+    /** ISO 8601 timestamp */
+    date: string;
+    snippet: string;
+    body?: string;
+    labels: string[];
+    isRead: boolean;
+}
+interface CalendarAttendee {
+    email: string;
+    displayName?: string;
+    responseStatus?: string;
+}
+interface CalendarEventRecord {
+    googleEventId: string;
+    calendarId: string;
+    account: string;
+    title: string;
+    description?: string;
+    location?: string;
+    /** ISO 8601 timestamp */
+    startAt: string;
+    /** ISO 8601 timestamp */
+    endAt: string;
+    allDay: boolean;
+    timezone?: string;
+    status: string;
+    organizerEmail: string;
+    attendees: CalendarAttendee[];
+    recurrence?: string[];
+    htmlLink?: string;
+}
+
+/**
+ * Google OAuth2 helpers.
+ *
+ * Uses dynamic `import('googleapis')` so the package is only required
+ * at runtime by consumers who actually use the Google connectors.
+ */
+
+type OAuth2Client = any;
+/**
+ * Create a Google OAuth2 client from app credentials.
+ */
+declare function createOAuth2Client(config: GoogleOAuthConfig): Promise<OAuth2Client>;
+/**
+ * Generate the consent screen URL for the given scopes.
+ */
+declare function getAuthUrl(client: OAuth2Client, scopes: string[]): string;
+/**
+ * Exchange an authorization code for tokens.
+ */
+declare function exchangeCode(client: OAuth2Client, code: string): Promise<GoogleTokens>;
+/**
+ * Load persisted tokens via a generic getter callback.
+ *
+ * @param getter  Reads a string value by key (e.g. SecretStore.get)
+ * @param accountKey  Unique key prefix for this account
+ */
+declare function loadTokens(getter: (key: string) => Promise<string | null>, accountKey: string): Promise<GoogleTokens | null>;
+/**
+ * Persist tokens via a generic setter callback.
+ *
+ * @param setter  Writes a string value by key (e.g. SecretStore.set)
+ * @param accountKey  Unique key prefix for this account
+ * @param tokens  Tokens to persist
+ */
+declare function saveTokens(setter: (key: string, value: string) => Promise<void>, accountKey: string, tokens: GoogleTokens): Promise<void>;
+/**
+ * Refresh the access token if it has expired (or is about to within 60 s).
+ *
+ * If the token was refreshed and a `saver` callback is provided, the new
+ * tokens are persisted automatically.
+ */
+declare function refreshIfNeeded(client: OAuth2Client, tokens: GoogleTokens, saver?: (tokens: GoogleTokens) => Promise<void>): Promise<GoogleTokens>;
+
+/**
+ * Gmail connector — pulls email metadata and optionally sends mail.
+ *
+ * Produces `EmailRecord` objects. Does NOT write to any database table;
+ * the consuming application decides how to store records.
+ */
+
+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>;
+}
+declare class GoogleGmailConnector implements Connector<EmailRecord> {
+    readonly id = "google-gmail";
+    readonly meta: ConnectorMeta;
+    private tokenLoader;
+    private tokenSaver;
+    private client;
+    private config;
+    private tokens;
+    private gmail;
+    constructor(opts: GmailConnectorOpts);
+    connect(config: GoogleConnectorConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        account?: string;
+        error?: string;
+    }>;
+    sync(options?: SyncOptions): Promise<SyncResult<EmailRecord>>;
+    /** Incremental sync using Gmail history API. */
+    private syncIncremental;
+    /** Full sync — list messages and fetch each one. */
+    private syncFull;
+    push(payload: EmailRecord): Promise<PushResult>;
+    private ensureConnected;
+    /** Fetch a single message by ID and parse into an EmailRecord. */
+    private fetchMessage;
+}
+
+/**
+ * Google Calendar connector — pulls calendar events.
+ *
+ * Produces `CalendarEventRecord` objects. Does NOT write to any database
+ * table; the consuming application decides how to store records.
+ */
+
+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>;
+}
+declare class GoogleCalendarConnector implements Connector<CalendarEventRecord> {
+    readonly id = "google-calendar";
+    readonly meta: ConnectorMeta;
+    private tokenLoader;
+    private tokenSaver;
+    private client;
+    private config;
+    private tokens;
+    private calendar;
+    constructor(opts: CalendarConnectorOpts);
+    connect(config: GoogleConnectorConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        account?: string;
+        error?: string;
+    }>;
+    sync(options?: SyncOptions): Promise<SyncResult<CalendarEventRecord>>;
+    /** Incremental sync using Calendar syncToken. */
+    private syncIncremental;
+    /** Full sync using timeMin. */
+    private syncFull;
+    private ensureConnected;
+    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 };

package/dist/connectors/google/index.js

@@ -0,0 +1,487 @@
+// 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 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;
+    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.`
+      );
+    }
+    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.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) };
+    }
+  }
+  // ── 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);
+}
+
+// src/connectors/google/calendar-connector.ts
+var GoogleCalendarConnector = class {
+  id = "google-calendar";
+  meta = {
+    displayName: "Google Calendar",
+    provider: "google",
+    dataType: "calendar"
+  };
+  tokenLoader;
+  tokenSaver;
+  client = null;
+  config = null;
+  tokens = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  calendar = null;
+  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.`
+      );
+    }
+    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 });
+  }
+  async disconnect() {
+    this.client = null;
+    this.calendar = null;
+    this.tokens = null;
+    this.config = null;
+  }
+  async healthCheck() {
+    try {
+      this.ensureConnected();
+      const res = await this.calendar.calendarList.list({ maxResults: 1 });
+      const primary = (res.data.items ?? []).find(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        (c) => c.primary
+      );
+      return { ok: true, account: primary?.id ?? this.config.account };
+    } catch (err) {
+      return { ok: false, error: errorMessage2(err) };
+    }
+  }
+  // ── Sync ───────────────────────────────────────────────────────
+  async sync(options) {
+    this.ensureConnected();
+    if (options?.cursor) {
+      return this.syncIncremental(options.cursor, options);
+    }
+    return this.syncFull(options);
+  }
+  /** Incremental sync using Calendar syncToken. */
+  async syncIncremental(syncToken, options) {
+    const calendarId = options?.filters?.calendarId ?? "primary";
+    const records = [];
+    const errors = [];
+    let pageToken;
+    let nextSyncToken;
+    try {
+      do {
+        const res = await this.calendar.events.list({
+          calendarId,
+          syncToken,
+          ...pageToken ? { pageToken } : {},
+          maxResults: options?.limit ? Math.min(options.limit - records.length, 250) : 250
+        });
+        for (const event of res.data.items ?? []) {
+          try {
+            records.push(this.mapEvent(event, calendarId));
+          } catch (err) {
+            errors.push({ id: event.id, error: errorMessage2(err) });
+          }
+          if (options?.limit && records.length >= options.limit) break;
+        }
+        pageToken = res.data.nextPageToken ?? void 0;
+        nextSyncToken = res.data.nextSyncToken ?? void 0;
+      } while (pageToken && (!options?.limit || records.length < options.limit));
+    } catch (err) {
+      if (err?.code === 410) {
+        return this.syncFull(options);
+      }
+      throw err;
+    }
+    return {
+      records,
+      cursor: nextSyncToken,
+      hasMore: !!pageToken,
+      errors
+    };
+  }
+  /** Full sync using timeMin. */
+  async syncFull(options) {
+    const calendarId = options?.filters?.calendarId ?? "primary";
+    const records = [];
+    const errors = [];
+    const maxResults = options?.limit ?? 250;
+    const timeMin = options?.since ? new Date(options.since).toISOString() : new Date(Date.now() - 30 * 24 * 60 * 60 * 1e3).toISOString();
+    let pageToken;
+    let nextSyncToken;
+    do {
+      const res = await this.calendar.events.list({
+        calendarId,
+        timeMin,
+        singleEvents: true,
+        orderBy: "startTime",
+        maxResults: Math.min(maxResults - records.length, 250),
+        ...pageToken ? { pageToken } : {}
+      });
+      for (const event of res.data.items ?? []) {
+        try {
+          records.push(this.mapEvent(event, calendarId));
+        } catch (err) {
+          errors.push({ id: event.id, error: errorMessage2(err) });
+        }
+        if (records.length >= maxResults) break;
+      }
+      pageToken = res.data.nextPageToken ?? void 0;
+      nextSyncToken = res.data.nextSyncToken ?? void 0;
+    } while (pageToken && records.length < maxResults);
+    return {
+      records,
+      cursor: nextSyncToken,
+      hasMore: !!pageToken,
+      errors
+    };
+  }
+  // ── Internals ─────────────────────────────────────────────────
+  ensureConnected() {
+    if (!this.calendar || !this.config) {
+      throw new Error("GoogleCalendarConnector is not connected. Call connect() first.");
+    }
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  mapEvent(event, calendarId) {
+    const start = event.start ?? {};
+    const end = event.end ?? {};
+    const allDay = !!start.date;
+    const startAt = allDay ? new Date(start.date).toISOString() : new Date(start.dateTime).toISOString();
+    const endAt = allDay ? new Date(end.date).toISOString() : new Date(end.dateTime).toISOString();
+    const attendees = (event.attendees ?? []).map(
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      (a) => ({
+        email: a.email,
+        displayName: a.displayName,
+        responseStatus: a.responseStatus
+      })
+    );
+    return {
+      googleEventId: event.id,
+      calendarId,
+      account: this.config.account,
+      title: event.summary ?? "(No title)",
+      description: event.description ?? void 0,
+      location: event.location ?? void 0,
+      startAt,
+      endAt,
+      allDay,
+      timezone: start.timeZone ?? void 0,
+      status: event.status ?? "confirmed",
+      organizerEmail: event.organizer?.email ?? "",
+      attendees,
+      recurrence: event.recurrence ?? void 0,
+      htmlLink: event.htmlLink ?? void 0
+    };
+  }
+};
+function errorMessage2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+export {
+  GoogleCalendarConnector,
+  GoogleGmailConnector,
+  createOAuth2Client,
+  exchangeCode,
+  getAuthUrl,
+  loadTokens,
+  refreshIfNeeded,
+  saveTokens
+};

package/dist/index.d.ts

@@ -2,6 +2,8 @@ import { C as ChannelAdapter, H as HealthStatus, I as InboundMessage } from './c
 export { A as Attachment, a as ChannelCapabilities, b as ChannelConfig, c as ChannelMeta, d as ChatType, F as FormattingMode, O as OutboundPayload, S as SendResult } from './channel-06G0vbIn.js';
 import { T as TokenUsage, L as LLMProvider, M as ModelInfo, R as ResolvedModel, C as ChatMessage } from './provider-qqJYv9nv.js';
 export { a as ChatParams, b as ChatResult, c as ContentBlock, d as ToolDefinition, e as ToolUse } from './provider-qqJYv9nv.js';
+import { C as ConnectorConfig } from './connector-DDahQw-2.js';
+export { a as Connector, b as ConnectorMeta, P as PushResult, S as SyncOptions, c as SyncResult } from './connector-DDahQw-2.js';
 import * as better_sqlite3 from 'better-sqlite3';
 
 /** Execution adapter types — Story 1.5 / 3.4 / 3.5 */
@@ -191,6 +193,11 @@ interface BotConfig {
         enabled: boolean;
         accounts?: Record<string, unknown>;
     } & Record<string, unknown>>;
+    connectors?: Record<string, {
+        enabled: boolean;
+        provider: string;
+        accounts?: Record<string, ConnectorConfig>;
+    } & Record<string, unknown>>;
     agents: AgentConfig[];
     providers: Record<string, {
         enabled: boolean;
@@ -1313,6 +1320,11 @@ declare class NdjsonLogger {
     close(): void;
 }
 
+/**
+ * @deprecated Use {@link Scheduler} from `botinabox` instead.
+ * HeartbeatScheduler uses in-memory setInterval which loses state on restart.
+ * The Scheduler class uses database-backed schedules with cron expressions.
+ */
 declare class HeartbeatScheduler {
     private wakeupQueue;
     private hooks;
@@ -1325,6 +1337,76 @@ declare class HeartbeatScheduler {
     stop(): void;
 }
 
+/**
+ * Scheduler — database-backed job scheduling with cron expressions.
+ *
+ * Supports one-time and recurring schedules. When a schedule fires,
+ * it emits the schedule's `action` as a hook event with the
+ * `action_config` payload. Consumers subscribe to handle the action.
+ *
+ * Replaces HeartbeatScheduler for recurring use cases.
+ */
+
+interface ScheduleDef {
+    name: string;
+    description?: string;
+    /** Cron expression for recurring schedules */
+    cron?: string;
+    /** ISO 8601 datetime for one-time schedules */
+    runAt?: string;
+    /** Hook event name to emit when fired */
+    action: string;
+    /** JSON-serializable payload passed to the hook */
+    actionConfig?: Record<string, unknown>;
+    timezone?: string;
+}
+interface Schedule {
+    id: string;
+    name: string;
+    description: string | null;
+    type: "one_time" | "recurring";
+    cron: string | null;
+    run_at: string | null;
+    timezone: string;
+    enabled: number;
+    action: string;
+    action_config: string;
+    last_fired_at: string | null;
+    next_fire_at: string | null;
+    created_at: string;
+    updated_at: string;
+    deleted_at: string | null;
+}
+declare class Scheduler {
+    private db;
+    private hooks;
+    private timer;
+    constructor(db: DataStore, hooks: HookBus);
+    /**
+     * Start the scheduler. Computes initial next_fire_at for schedules
+     * that don't have one, then polls for due schedules.
+     */
+    start(pollIntervalMs?: number): Promise<void>;
+    stop(): void;
+    /** Check for and fire due schedules. */
+    tick(): Promise<void>;
+    /** Register a new schedule. */
+    register(def: ScheduleDef): Promise<string>;
+    /** Update an existing schedule. */
+    update(id: string, changes: Partial<Pick<ScheduleDef, "name" | "cron" | "runAt" | "action" | "actionConfig" | "timezone" | "description">> & {
+        enabled?: boolean;
+    }): Promise<void>;
+    /** Soft-delete a schedule. */
+    unregister(id: string): Promise<void>;
+    /** List schedules, optionally filtered. */
+    list(filter?: {
+        enabled?: boolean;
+        action?: string;
+    }): Promise<Schedule[]>;
+    /** Compute next_fire_at for any enabled schedule missing it. */
+    private initializeNextFireTimes;
+}
+
 /**
  * Creates a config revision record with before/after snapshots.
  * Note: uses config_revisions table with config_yaml storing JSON of {agentId, before, after}.
@@ -1485,4 +1567,4 @@ declare function isLoginRequired(stdout: string): boolean;
 /** Rewrite local image paths to prevent CLI auto-embedding as vision content. */
 declare function deactivateLocalImagePaths(prompt: string): string;
 
-export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, ChatMessage, ChatSessionManager, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, DataStoreError, type DomainEntityContextOptions, type DomainSchemaOptions, EVENTS, type EntityColumnDef, type EntityConfig, type EntityContextDef, type EntityFileSpec, type EntitySource, type ExecutionAdapter, type Filter, HealthStatus, HeartbeatScheduler, HookBus, type HookHandler, type HookOptions, type HookRegistration, InboundMessage, LLMProvider, MAX_CHAIN_DEPTH, MessagePipeline, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PkLookup, ProviderRegistry, type QueryOptions, RUN_STATUSES, type RelationDef, type RenderConfig, ResolvedModel, type RetryPolicy, type Row, type RunContext, RunManager, type RunResult, type RunStatus, type SanitizerOptions, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, type SeedItem, SessionKey, SessionManager, type SqliteAdapter, type StepRef, TASK_STATUSES, type TableDefinition, type TableInfoRow, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, type Unsubscribe, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, areDependenciesMet, buildAgentBindings, buildChainOrigin, buildProcessEnv, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, createConfigRevision, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, formatText, getConfig, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, loadConfig, parseClaudeStream, parseVersion, runPackageMigrations, sanitize, topologicalSort, validateConfig };
+export { AGENT_STATUSES, type AgentConfig, type AgentDefinition, type AgentFilter, type AgentRecord, AgentRegistry, type AgentStatus, ApiExecutionAdapter, AuditEmitter, type AuditEvent, BackupManager, type BotConfig, type BudgetCheck, type BudgetConfig, BudgetController, CORE_MIGRATIONS, ChannelAdapter, ChannelRegistry, ChannelRegistryError, ChatMessage, ChatSessionManager, CliExecutionAdapter, type ColumnValidator, ColumnValidatorImpl, type ConfigLoadError, type ConfigLoadResult, ConnectorConfig, DEFAULTS, DEFAULT_CONFIG, type DataConfig, DataStore, DataStoreError, type DomainEntityContextOptions, type DomainSchemaOptions, EVENTS, type EntityColumnDef, type EntityConfig, type EntityContextDef, type EntityFileSpec, type EntitySource, type ExecutionAdapter, type Filter, HealthStatus, HeartbeatScheduler, HookBus, type HookHandler, type HookOptions, type HookRegistration, InboundMessage, LLMProvider, MAX_CHAIN_DEPTH, MessagePipeline, type ModelConfig, ModelInfo, ModelRouter, NdjsonLogger, NotificationQueue, type PackageMigration, type PackageUpdate, type ParsedStream, type PkLookup, ProviderRegistry, type QueryOptions, RUN_STATUSES, type RelationDef, type RenderConfig, ResolvedModel, type RetryPolicy, type Row, type RunContext, RunManager, type RunResult, type RunStatus, type SanitizerOptions, type Schedule, type ScheduleDef, Scheduler, type SchemaError, type SecretInput, type SecretMeta, SecretStore, type SecurityConfig, type SeedItem, SessionKey, SessionManager, type SqliteAdapter, type StepRef, TASK_STATUSES, type TableDefinition, type TableInfoRow, type TaskDefinition, TaskQueue, type TaskRecord, type TaskStatus, TokenUsage, type Unsubscribe, UpdateChecker, type UpdateConfig, UpdateManager, type UpdateManifest, type UsageSummary, type User, type UserInput, UserRegistry, WakeupQueue, type WorkflowConfigEntry, type WorkflowDefinition$1 as WorkflowDefinition, WorkflowEngine, type WorkflowRunRecord, type WorkflowRunStatus, type WorkflowStep$1 as WorkflowStep, type WorkflowStepConfig, type WorkflowTrigger, _resetConfig, areDependenciesMet, buildAgentBindings, buildChainOrigin, buildProcessEnv, checkAllowlist, checkChainDepth, checkMentionGate, chunkText, classifyUpdate, compareVersions, createConfigRevision, deactivateLocalImagePaths, defineCoreEntityContexts, defineCoreTables, defineDomainEntityContexts, defineDomainTables, detectCycle, discoverChannels, discoverProviders, formatText, getConfig, initConfig, interpolate, interpolateEnv, isLoginRequired, isMaxTurns, loadConfig, parseClaudeStream, parseVersion, runPackageMigrations, sanitize, topologicalSort, validateConfig };

package/dist/index.js

@@ -1580,6 +1580,29 @@ function defineCoreTables(db) {
       "FOREIGN KEY (user_id) REFERENCES users(id)"
     ]
   });
+  db.define("schedules", {
+    columns: {
+      id: "TEXT PRIMARY KEY",
+      name: "TEXT NOT NULL",
+      description: "TEXT",
+      type: "TEXT NOT NULL DEFAULT 'recurring'",
+      cron: "TEXT",
+      run_at: "TEXT",
+      timezone: "TEXT DEFAULT 'UTC'",
+      enabled: "INTEGER NOT NULL DEFAULT 1",
+      action: "TEXT NOT NULL",
+      action_config: "TEXT DEFAULT '{}'",
+      last_fired_at: "TEXT",
+      next_fire_at: "TEXT",
+      created_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      updated_at: "TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP",
+      deleted_at: "TEXT"
+    },
+    tableConstraints: [
+      "CREATE UNIQUE INDEX IF NOT EXISTS idx_schedules_name ON schedules(name) WHERE deleted_at IS NULL",
+      "CREATE INDEX IF NOT EXISTS idx_schedules_next ON schedules(enabled, next_fire_at) WHERE deleted_at IS NULL"
+    ]
+  });
   db.define("secrets", {
     columns: {
       id: "TEXT PRIMARY KEY",
@@ -1618,6 +1641,34 @@ var CORE_MIGRATIONS = [
   {
     version: "003_runs_cost_index",
     sql: `CREATE INDEX IF NOT EXISTS idx_runs_cost ON runs(agent_id, completed_at) WHERE cost_cents > 0;`
+  },
+  {
+    version: "004_schedules_table",
+    sql: `CREATE TABLE IF NOT EXISTS schedules (
+            id TEXT PRIMARY KEY,
+            name TEXT NOT NULL,
+            description TEXT,
+            type TEXT NOT NULL DEFAULT 'recurring',
+            cron TEXT,
+            run_at TEXT,
+            timezone TEXT DEFAULT 'UTC',
+            enabled INTEGER NOT NULL DEFAULT 1,
+            action TEXT NOT NULL,
+            action_config TEXT DEFAULT '{}',
+            last_fired_at TEXT,
+            next_fire_at TEXT,
+            created_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            updated_at TEXT NOT NULL DEFAULT CURRENT_TIMESTAMP,
+            deleted_at TEXT
+          )`
+  },
+  {
+    version: "005_schedules_name_index",
+    sql: `CREATE UNIQUE INDEX IF NOT EXISTS idx_schedules_name ON schedules(name) WHERE deleted_at IS NULL`
+  },
+  {
+    version: "006_schedules_next_index",
+    sql: `CREATE INDEX IF NOT EXISTS idx_schedules_next ON schedules(enabled, next_fire_at) WHERE deleted_at IS NULL`
   }
 ];
 
@@ -3387,6 +3438,194 @@ var HeartbeatScheduler = class {
   }
 };
 
+// src/core/orchestrator/scheduler.ts
+import { parseExpression } from "cron-parser";
+import { v4 as uuid } from "uuid";
+function computeNextFire(cron, timezone, after) {
+  const interval = parseExpression(cron, {
+    currentDate: after ?? /* @__PURE__ */ new Date(),
+    tz: timezone
+  });
+  return interval.next().toISOString();
+}
+var Scheduler = class {
+  constructor(db, hooks) {
+    this.db = db;
+    this.hooks = hooks;
+  }
+  db;
+  hooks;
+  timer = null;
+  /**
+   * Start the scheduler. Computes initial next_fire_at for schedules
+   * that don't have one, then polls for due schedules.
+   */
+  async start(pollIntervalMs = 3e4) {
+    await this.initializeNextFireTimes();
+    this.timer = setInterval(() => {
+      void this.tick();
+    }, pollIntervalMs);
+    void this.tick();
+  }
+  stop() {
+    if (this.timer) {
+      clearInterval(this.timer);
+      this.timer = null;
+    }
+  }
+  /** Check for and fire due schedules. */
+  async tick() {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const schedules = (await this.db.query("schedules", {
+      where: { enabled: 1 }
+    })).filter(
+      (s) => s["deleted_at"] == null && s["next_fire_at"] != null && s["next_fire_at"] <= now
+    );
+    for (const schedule of schedules) {
+      try {
+        const config = JSON.parse(schedule.action_config || "{}");
+        await this.hooks.emit(schedule.action, {
+          schedule_id: schedule.id,
+          schedule_name: schedule.name,
+          ...config
+        });
+        await this.hooks.emit("schedule.fired", {
+          schedule_id: schedule.id,
+          schedule_name: schedule.name,
+          action: schedule.action,
+          fired_at: now
+        });
+        if (schedule.type === "recurring" && schedule.cron) {
+          const nextFire = computeNextFire(
+            schedule.cron,
+            schedule.timezone,
+            /* @__PURE__ */ new Date()
+          );
+          await this.db.update(
+            "schedules",
+            { id: schedule.id },
+            {
+              last_fired_at: now,
+              next_fire_at: nextFire,
+              updated_at: now
+            }
+          );
+        } else {
+          await this.db.update(
+            "schedules",
+            { id: schedule.id },
+            {
+              last_fired_at: now,
+              next_fire_at: null,
+              enabled: 0,
+              updated_at: now
+            }
+          );
+        }
+      } catch (err) {
+        console.error(
+          `[Scheduler] Error firing schedule "${schedule.name}":`,
+          err
+        );
+        await this.hooks.emit("schedule.error", {
+          schedule_id: schedule.id,
+          schedule_name: schedule.name,
+          error: String(err)
+        });
+      }
+    }
+  }
+  /** Register a new schedule. */
+  async register(def) {
+    const id = uuid();
+    const type = def.cron ? "recurring" : "one_time";
+    const timezone = def.timezone ?? "UTC";
+    let nextFire = null;
+    if (def.cron) {
+      nextFire = computeNextFire(def.cron, timezone);
+    } else if (def.runAt) {
+      nextFire = new Date(def.runAt).toISOString();
+    }
+    await this.db.insert("schedules", {
+      id,
+      name: def.name,
+      description: def.description ?? null,
+      type,
+      cron: def.cron ?? null,
+      run_at: def.runAt ?? null,
+      timezone,
+      enabled: 1,
+      action: def.action,
+      action_config: JSON.stringify(def.actionConfig ?? {}),
+      next_fire_at: nextFire
+    });
+    return id;
+  }
+  /** Update an existing schedule. */
+  async update(id, changes) {
+    const row = {
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    if (changes.name !== void 0) row["name"] = changes.name;
+    if (changes.description !== void 0) row["description"] = changes.description;
+    if (changes.action !== void 0) row["action"] = changes.action;
+    if (changes.actionConfig !== void 0)
+      row["action_config"] = JSON.stringify(changes.actionConfig);
+    if (changes.enabled !== void 0) row["enabled"] = changes.enabled ? 1 : 0;
+    if (changes.cron !== void 0) {
+      row["cron"] = changes.cron;
+      row["type"] = "recurring";
+      row["run_at"] = null;
+      row["next_fire_at"] = computeNextFire(
+        changes.cron,
+        changes.timezone ?? "UTC"
+      );
+    } else if (changes.runAt !== void 0) {
+      row["run_at"] = changes.runAt;
+      row["type"] = "one_time";
+      row["cron"] = null;
+      row["next_fire_at"] = new Date(changes.runAt).toISOString();
+    }
+    if (changes.timezone !== void 0) row["timezone"] = changes.timezone;
+    await this.db.update("schedules", { id }, row);
+  }
+  /** Soft-delete a schedule. */
+  async unregister(id) {
+    await this.db.update("schedules", { id }, {
+      enabled: 0,
+      deleted_at: (/* @__PURE__ */ new Date()).toISOString(),
+      updated_at: (/* @__PURE__ */ new Date()).toISOString()
+    });
+  }
+  /** List schedules, optionally filtered. */
+  async list(filter) {
+    const where = {};
+    if (filter?.enabled !== void 0) where["enabled"] = filter.enabled ? 1 : 0;
+    if (filter?.action !== void 0) where["action"] = filter.action;
+    return (await this.db.query("schedules", { where })).filter((s) => s["deleted_at"] == null);
+  }
+  /** Compute next_fire_at for any enabled schedule missing it. */
+  async initializeNextFireTimes() {
+    const schedules = (await this.db.query("schedules", { where: { enabled: 1 } })).filter(
+      (s) => s["deleted_at"] == null && s["next_fire_at"] == null
+    );
+    for (const s of schedules) {
+      let nextFire = null;
+      if (s.type === "recurring" && s.cron) {
+        nextFire = computeNextFire(s.cron, s.timezone);
+      } else if (s.type === "one_time" && s.run_at) {
+        nextFire = new Date(s.run_at).toISOString();
+      }
+      if (nextFire) {
+        await this.db.update("schedules", { id: s.id }, {
+          next_fire_at: nextFire,
+          updated_at: (/* @__PURE__ */ new Date()).toISOString()
+        });
+      }
+    }
+  }
+};
+
 // src/core/orchestrator/adapters/api-adapter.ts
 import { readFileSync as readFileSync3, existsSync as existsSync2 } from "fs";
 
@@ -3963,6 +4202,7 @@ export {
   ProviderRegistry,
   RUN_STATUSES,
   RunManager,
+  Scheduler,
   SecretStore,
   SessionKey,
   SessionManager,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",
@@ -33,6 +33,10 @@
     "./webhook": {
       "import": "./dist/channels/webhook/index.js",
       "types": "./dist/channels/webhook/index.d.ts"
+    },
+    "./google": {
+      "import": "./dist/connectors/google/index.js",
+      "types": "./dist/connectors/google/index.d.ts"
     }
   },
   "bin": {
@@ -46,12 +50,14 @@
   "dependencies": {
     "@types/uuid": "^10.0.0",
     "ajv": "^8.17.1",
+    "cron-parser": "^4.9.0",
     "latticesql": "^0.18.0",
     "uuid": "^13.0.0",
     "yaml": "^2.7.0"
   },
   "peerDependencies": {
     "@anthropic-ai/sdk": "^0.52.0",
+    "googleapis": ">=140.0.0",
     "openai": "^4.104.0"
   },
   "peerDependenciesMeta": {
@@ -60,12 +66,16 @@
     },
     "openai": {
       "optional": true
+    },
+    "googleapis": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@anthropic-ai/sdk": "^0.52.0",
     "@types/better-sqlite3": "^7.6.12",
     "@types/node": "^22.10.0",
+    "googleapis": "^171.4.0",
     "openai": "^4.104.0",
     "tsup": "^8.3.5",
     "typescript": "^5.7.2",