botinabox 2.5.0 → 2.5.2

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

@@ -54,6 +54,29 @@ interface EmailRecord {
     labels: string[];
     isRead: boolean;
 }
+interface DriveOwner {
+    displayName: string;
+    emailAddress: string;
+}
+interface DriveFileRecord {
+    driveFileId: string;
+    account: string;
+    name: string;
+    mimeType: string;
+    webViewLink: string;
+    webContentLink?: string;
+    /** ISO 8601 */
+    modifiedTime: string;
+    /** ISO 8601 */
+    createdTime: string;
+    size?: number;
+    parents?: string[];
+    description?: string;
+    owners: DriveOwner[];
+    lastModifyingUser?: DriveOwner;
+    starred: boolean;
+    trashed: boolean;
+}
 interface CalendarAttendee {
     email: string;
     displayName?: string;
@@ -209,4 +232,47 @@ 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 GoogleServiceAccountConfig, type GoogleTokens, createOAuth2Client, createServiceAccountClient, exchangeCode, getAuthUrl, loadTokens, refreshIfNeeded, saveTokens };
+/**
+ * Google Drive connector — pulls file metadata from Drive.
+ *
+ * Produces `DriveFileRecord` objects. Does NOT write to any database
+ * table; the consuming application decides how to store records.
+ *
+ * Supports incremental sync via Drive Changes API (startPageToken)
+ * and full sync via files.list with optional folder/MIME filters.
+ */
+
+interface DriveConnectorOpts {
+    /** 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 GoogleDriveConnector implements Connector<DriveFileRecord> {
+    readonly id = "google-drive";
+    readonly meta: ConnectorMeta;
+    private tokenLoader?;
+    private tokenSaver?;
+    private client;
+    private config;
+    private tokens;
+    private drive;
+    constructor(opts?: DriveConnectorOpts);
+    connect(config: GoogleConnectorConfig): Promise<void>;
+    disconnect(): Promise<void>;
+    healthCheck(): Promise<{
+        ok: boolean;
+        account?: string;
+        error?: string;
+    }>;
+    authenticate(codeProvider: (authUrl: string) => Promise<string>): Promise<AuthResult>;
+    sync(options?: SyncOptions): Promise<SyncResult<DriveFileRecord>>;
+    /** Incremental sync using Drive Changes API. */
+    private syncIncremental;
+    /** Full sync using files.list. */
+    private syncFull;
+    private ensureConnected;
+    private mapFile;
+}
+
+export { type CalendarAttendee, type CalendarConnectorOpts, type CalendarEventRecord, type DriveConnectorOpts, type DriveFileRecord, type DriveOwner, type EmailAddress, type EmailRecord, type GmailConnectorOpts, GoogleCalendarConnector, type GoogleConnectorConfig, GoogleDriveConnector, GoogleGmailConnector, type GoogleOAuthConfig, type GoogleServiceAccountConfig, type GoogleTokens, createOAuth2Client, createServiceAccountClient, exchangeCode, getAuthUrl, loadTokens, refreshIfNeeded, saveTokens };

package/dist/connectors/google/index.js

@@ -235,8 +235,248 @@ var GoogleCalendarConnector = class {
 function errorMessage(err) {
   return err instanceof Error ? err.message : String(err);
 }
+
+// src/connectors/google/drive-connector.ts
+var FILE_FIELDS = "id, name, mimeType, webViewLink, webContentLink, modifiedTime, createdTime, size, parents, description, owners, lastModifyingUser, starred, trashed";
+var GoogleDriveConnector = class {
+  id = "google-drive";
+  meta = {
+    displayName: "Google Drive",
+    provider: "google",
+    dataType: "document"
+  };
+  tokenLoader;
+  tokenSaver;
+  client = null;
+  config = null;
+  tokens = null;
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  drive = 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/drive.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.drive = google.drive({ version: "v3", auth: this.client });
+  }
+  async disconnect() {
+    this.client = null;
+    this.drive = null;
+    this.tokens = null;
+    this.config = null;
+  }
+  async healthCheck() {
+    try {
+      this.ensureConnected();
+      const res = await this.drive.about.get({ fields: "user" });
+      return { ok: true, account: res.data.user?.emailAddress ?? this.config.account };
+    } catch (err) {
+      return { ok: false, error: errorMessage2(err) };
+    }
+  }
+  // ── Auth ───────────────────────────────────────────────────────
+  async authenticate(codeProvider) {
+    if (!this.config) {
+      return { success: false, error: "Call connect() first." };
+    }
+    try {
+      if (!this.config.oauth) {
+        return { success: false, error: "OAuth config required. 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/drive.readonly"
+      ];
+      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.drive = google.drive({ version: "v3", auth: this.client });
+      return { success: true, account: this.config.account };
+    } catch (err) {
+      return { success: 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 Drive Changes API. */
+  async syncIncremental(startPageToken, options) {
+    const records = [];
+    const errors = [];
+    let pageToken = startPageToken;
+    let newStartPageToken;
+    try {
+      do {
+        const res = await this.drive.changes.list({
+          pageToken,
+          fields: `nextPageToken, newStartPageToken, changes(fileId, removed, file(${FILE_FIELDS}))`,
+          pageSize: options?.limit ? Math.min(options.limit - records.length, 100) : 100
+        });
+        for (const change of res.data.changes ?? []) {
+          try {
+            if (change.removed || !change.file) {
+              if (change.fileId) {
+                records.push({
+                  driveFileId: change.fileId,
+                  account: this.config.account,
+                  name: "",
+                  mimeType: "",
+                  webViewLink: "",
+                  modifiedTime: (/* @__PURE__ */ new Date()).toISOString(),
+                  createdTime: "",
+                  owners: [],
+                  starred: false,
+                  trashed: true
+                });
+              }
+            } else {
+              records.push(this.mapFile(change.file));
+            }
+          } catch (err) {
+            errors.push({ id: change.fileId ?? "unknown", error: errorMessage2(err) });
+          }
+          if (options?.limit && records.length >= options.limit) break;
+        }
+        pageToken = res.data.nextPageToken ?? void 0;
+        newStartPageToken = res.data.newStartPageToken ?? void 0;
+      } while (pageToken && (!options?.limit || records.length < options.limit));
+    } catch (err) {
+      if (err?.code === 403 || err?.code === 404) {
+        return this.syncFull(options);
+      }
+      throw err;
+    }
+    return {
+      records,
+      cursor: newStartPageToken,
+      hasMore: !!pageToken,
+      errors
+    };
+  }
+  /** Full sync using files.list. */
+  async syncFull(options) {
+    const records = [];
+    const errors = [];
+    const maxResults = options?.limit ?? 500;
+    const queryParts = ["trashed = false"];
+    const folderId = options?.filters?.folderId;
+    if (folderId) {
+      queryParts.push(`'${folderId}' in parents`);
+    }
+    const mimeType = options?.filters?.mimeType;
+    if (mimeType) {
+      queryParts.push(`mimeType = '${mimeType}'`);
+    }
+    if (options?.since) {
+      queryParts.push(`modifiedTime > '${new Date(options.since).toISOString()}'`);
+    }
+    const q = queryParts.join(" and ");
+    let pageToken;
+    do {
+      const res = await this.drive.files.list({
+        q,
+        fields: `nextPageToken, files(${FILE_FIELDS})`,
+        orderBy: "modifiedTime desc",
+        pageSize: Math.min(maxResults - records.length, 100),
+        ...pageToken ? { pageToken } : {}
+      });
+      for (const file of res.data.files ?? []) {
+        try {
+          records.push(this.mapFile(file));
+        } catch (err) {
+          errors.push({ id: file.id, error: errorMessage2(err) });
+        }
+        if (records.length >= maxResults) break;
+      }
+      pageToken = res.data.nextPageToken ?? void 0;
+    } while (pageToken && records.length < maxResults);
+    const tokenRes = await this.drive.changes.getStartPageToken({});
+    const cursor = tokenRes.data.startPageToken ?? void 0;
+    return {
+      records,
+      cursor,
+      hasMore: !!pageToken,
+      errors
+    };
+  }
+  // ── Internals ─────────────────────────────────────────────────
+  ensureConnected() {
+    if (!this.drive || !this.config) {
+      throw new Error("GoogleDriveConnector is not connected. Call connect() first.");
+    }
+  }
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  mapFile(file) {
+    const mapOwner = (o) => ({
+      displayName: o?.displayName ?? "",
+      emailAddress: o?.emailAddress ?? ""
+    });
+    return {
+      driveFileId: file.id,
+      account: this.config.account,
+      name: file.name ?? "(Untitled)",
+      mimeType: file.mimeType ?? "",
+      webViewLink: file.webViewLink ?? "",
+      webContentLink: file.webContentLink ?? void 0,
+      modifiedTime: file.modifiedTime ?? (/* @__PURE__ */ new Date()).toISOString(),
+      createdTime: file.createdTime ?? "",
+      size: file.size ? parseInt(file.size, 10) : void 0,
+      parents: file.parents ?? void 0,
+      description: file.description ?? void 0,
+      owners: (file.owners ?? []).map(mapOwner),
+      lastModifyingUser: file.lastModifyingUser ? mapOwner(file.lastModifyingUser) : void 0,
+      starred: file.starred ?? false,
+      trashed: file.trashed ?? false
+    };
+  }
+};
+function errorMessage2(err) {
+  return err instanceof Error ? err.message : String(err);
+}
 export {
   GoogleCalendarConnector,
+  GoogleDriveConnector,
   GoogleGmailConnector,
   createOAuth2Client,
   createServiceAccountClient,

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

@@ -0,0 +1,48 @@
+/**
+ * Google OAuth2 helpers.
+ *
+ * Uses dynamic `import('googleapis')` so the package is only required
+ * at runtime by consumers who actually use the Google connectors.
+ */
+import type { GoogleOAuthConfig, GoogleServiceAccountConfig, GoogleTokens } from './types.js';
+type OAuth2Client = any;
+/**
+ * Create a Google OAuth2 client from app credentials.
+ */
+export declare function createOAuth2Client(config: GoogleOAuthConfig): Promise<OAuth2Client>;
+/**
+ * Generate the consent screen URL for the given scopes.
+ */
+export declare function getAuthUrl(client: OAuth2Client, scopes: string[]): string;
+/**
+ * Exchange an authorization code for tokens.
+ */
+export 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.
+ */
+export declare function createServiceAccountClient(config: GoogleServiceAccountConfig, scopes: string[]): Promise<OAuth2Client>;
+/**
+ * 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
+ */
+export 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
+ */
+export 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.
+ */
+export declare function refreshIfNeeded(client: OAuth2Client, tokens: GoogleTokens, saver?: (tokens: GoogleTokens) => Promise<void>): Promise<GoogleTokens>;
+export {};

package/dist/connectors/google/oauth.js

@@ -0,0 +1,112 @@
+/**
+ * Google OAuth2 helpers.
+ *
+ * Uses dynamic `import('googleapis')` so the package is only required
+ * at runtime by consumers who actually use the Google connectors.
+ */
+// ── Lazy googleapis import ─────────────────────────────────────────
+let _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;
+}
+// ── Public helpers ─────────────────────────────────────────────────
+/**
+ * Create a Google OAuth2 client from app credentials.
+ */
+export async function createOAuth2Client(config) {
+    const google = await getGoogle();
+    return new google.auth.OAuth2(config.clientId, config.clientSecret, config.redirectUri);
+}
+/**
+ * Generate the consent screen URL for the given scopes.
+ */
+export function getAuthUrl(client, scopes) {
+    return client.generateAuthUrl({
+        access_type: 'offline',
+        prompt: 'consent',
+        scope: scopes,
+    });
+}
+/**
+ * Exchange an authorization code for tokens.
+ */
+export async function exchangeCode(client, code) {
+    const { tokens } = await client.getToken(code);
+    return tokens;
+}
+// ── Service account auth ──────────────────────────────────────────
+/**
+ * Create an authenticated client using a service account with
+ * domain-wide delegation (impersonation). No browser flow needed.
+ */
+export 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();
+}
+// ── Token persistence ──────────────────────────────────────────────
+/**
+ * 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
+ */
+export async function loadTokens(getter, accountKey) {
+    const raw = await getter(`google_tokens:${accountKey}`);
+    if (!raw)
+        return null;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return 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
+ */
+export async function saveTokens(setter, accountKey, tokens) {
+    await setter(`google_tokens:${accountKey}`, JSON.stringify(tokens));
+}
+/**
+ * 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.
+ */
+export async function refreshIfNeeded(client, tokens, saver) {
+    const buffer = 60_000; // 60 seconds
+    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 ?? undefined,
+        token_type: credentials.token_type ?? 'Bearer',
+    };
+    if (saver) {
+        await saver(refreshed);
+    }
+    return refreshed;
+}

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

@@ -0,0 +1,78 @@
+/** Google connector types. */
+import type { ConnectorConfig } from '../../shared/types/connector.js';
+export interface GoogleOAuthConfig {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+}
+export interface GoogleTokens {
+    access_token: string;
+    refresh_token?: string;
+    expiry_date?: number;
+    token_type: string;
+}
+export 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;
+}
+export interface GoogleConnectorConfig extends ConnectorConfig {
+    /** Google account email */
+    account: string;
+    /** OAuth2 user auth (requires browser flow) */
+    oauth?: GoogleOAuthConfig;
+    /** Service account auth (headless, for cloud deployments) */
+    serviceAccount?: GoogleServiceAccountConfig;
+    scopes?: string[];
+}
+export interface EmailAddress {
+    name?: string;
+    email: string;
+}
+export 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;
+}
+export interface CalendarAttendee {
+    email: string;
+    displayName?: string;
+    responseStatus?: string;
+}
+export 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;
+}

package/dist/connectors/google/types.js

@@ -0,0 +1,2 @@
+/** Google connector types. */
+export {};

package/dist/core/chat/auto-discovery.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Auto-discovery for channel adapters.
+ * Scans @botinabox/* packages for botinabox.type === 'channel'.
+ * Story 4.1
+ */
+import type { ChannelAdapter } from "./types.js";
+type Importer = (packageName: string) => Promise<unknown>;
+/**
+ * Scans nodeModulesPath/@botinabox/{pkg}/package.json for each package in the scope.
+ * If pkg.botinabox?.type === 'channel', dynamically imports the package
+ * and returns the discovered ChannelAdapter instances.
+ *
+ * The optional importer parameter allows injection for testing.
+ */
+export declare function discoverChannels(nodeModulesPath: string, importer?: Importer): Promise<ChannelAdapter[]>;
+export {};

package/dist/core/chat/auto-discovery.js

@@ -0,0 +1,54 @@
+/**
+ * Auto-discovery for channel adapters.
+ * Scans @botinabox/* packages for botinabox.type === 'channel'.
+ * Story 4.1
+ */
+import { readdir, readFile } from "node:fs/promises";
+import { join } from "node:path";
+/**
+ * Scans nodeModulesPath/@botinabox/{pkg}/package.json for each package in the scope.
+ * If pkg.botinabox?.type === 'channel', dynamically imports the package
+ * and returns the discovered ChannelAdapter instances.
+ *
+ * The optional importer parameter allows injection for testing.
+ */
+export async function discoverChannels(nodeModulesPath, importer = (name) => import(name)) {
+    const scopeDir = join(nodeModulesPath, "@botinabox");
+    let entries;
+    try {
+        entries = await readdir(scopeDir);
+    }
+    catch {
+        // No @botinabox scope directory — gracefully return empty
+        return [];
+    }
+    const adapters = [];
+    for (const entry of entries) {
+        const pkgPath = join(scopeDir, entry, "package.json");
+        let pkg;
+        try {
+            const raw = await readFile(pkgPath, "utf8");
+            pkg = JSON.parse(raw);
+        }
+        catch {
+            continue;
+        }
+        const botinabox = pkg.botinabox;
+        if (botinabox?.type !== "channel") {
+            continue;
+        }
+        const packageName = pkg.name;
+        if (!packageName) {
+            continue;
+        }
+        try {
+            const mod = await importer(packageName);
+            const adapter = "default" in mod && mod.default ? mod.default : mod;
+            adapters.push(adapter);
+        }
+        catch {
+            // Failed to import — skip silently
+        }
+    }
+    return adapters;
+}

package/dist/core/chat/channel-registry.d.ts

@@ -0,0 +1,45 @@
+/**
+ * ChannelRegistry — manages channel adapter lifecycle.
+ * Story 4.1
+ */
+import type { ChannelAdapter, HealthStatus } from "./types.js";
+export declare class ChannelRegistryError extends Error {
+    constructor(message: string);
+}
+export declare class ChannelRegistry {
+    private readonly adapters;
+    private started;
+    /**
+     * Register a channel adapter.
+     * Throws if an adapter with the same id is already registered.
+     * If registry is already started, immediately connects the adapter.
+     */
+    register(adapter: ChannelAdapter, config?: unknown): void;
+    /**
+     * Unregister a channel adapter.
+     * Disconnects the adapter if it exists.
+     */
+    unregister(id: string): Promise<void>;
+    /**
+     * Reconfigure an adapter: disconnect, update config, reconnect.
+     */
+    reconfigure(id: string, config: unknown): Promise<void>;
+    /**
+     * Run health checks on all registered adapters.
+     */
+    healthCheck(): Promise<Record<string, HealthStatus>>;
+    /** Check if an adapter is registered. */
+    has(id: string): boolean;
+    /** Get an adapter by ID. */
+    get(id: string): ChannelAdapter | undefined;
+    /** List all registered adapters. */
+    list(): ChannelAdapter[];
+    /**
+     * Start: connect all registered adapters and mark registry as started.
+     */
+    start(): Promise<void>;
+    /**
+     * Stop: disconnect all registered adapters.
+     */
+    stop(): Promise<void>;
+}