botinabox 2.5.2 → 2.5.3

package/dist/connectors/google/gmail-connector.js

@@ -1,345 +0,0 @@
-/**
- * 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.
- */
-import { createOAuth2Client, createServiceAccountClient, getAuthUrl, exchangeCode, loadTokens, saveTokens, refreshIfNeeded, } from './oauth.js';
-// ── Connector ──────────────────────────────────────────────────────
-export class GoogleGmailConnector {
-    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) {
-            // Service account auth — headless, no browser
-            this.client = await createServiceAccountClient(config.serviceAccount, scopes);
-        }
-        else if (config.oauth) {
-            // OAuth2 user flow — requires tokens from prior browser auth
-            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)
-                : undefined);
-            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 = 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 ?? undefined;
-        } 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) {
-            // Gmail `after:` uses epoch seconds
-            const epoch = Math.floor(new Date(options.since).getTime() / 1000);
-            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 ?? undefined;
-        } while (pageToken && collected < maxResults);
-        // Get current historyId for future incremental syncs
-        const profile = await this.gmail.users.getProfile({ userId: 'me' });
-        const cursor = profile.data.historyId ?? undefined;
-        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\n`
-                : '';
-            const bccHeader = payload.bcc.length
-                ? `Bcc: ${payload.bcc.map(formatAddress).join(', ')}\r\n`
-                : '';
-            const mime = [
-                `To: ${toHeader}\r\n`,
-                ccHeader,
-                bccHeader,
-                `Subject: ${payload.subject}\r\n`,
-                `Content-Type: text/plain; charset="UTF-8"\r\n`,
-                `\r\n`,
-                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: 'full',
-        });
-        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 ?? '',
-            body: extractPlainTextBody(msg.payload),
-            labels: msg.labelIds ?? [],
-            isRead: !(msg.labelIds ?? []).includes('UNREAD'),
-        };
-    }
-}
-// ── MIME body extraction ──────────────────────────────────────────
-// eslint-disable-next-line @typescript-eslint/no-explicit-any
-function extractPlainTextBody(payload) {
-    if (!payload)
-        return undefined;
-    // Single-part message: body is directly on the payload
-    if (payload.mimeType === 'text/plain' && payload.body?.data) {
-        return decodeBase64Url(payload.body.data);
-    }
-    // Multipart: recurse through parts, prefer text/plain
-    if (payload.parts) {
-        // First pass: look for text/plain
-        for (const part of payload.parts) {
-            if (part.mimeType === 'text/plain' && part.body?.data) {
-                return decodeBase64Url(part.body.data);
-            }
-        }
-        // Second pass: recurse into nested multipart
-        for (const part of payload.parts) {
-            if (part.mimeType?.startsWith('multipart/')) {
-                const result = extractPlainTextBody(part);
-                if (result)
-                    return result;
-            }
-        }
-    }
-    return undefined;
-}
-function decodeBase64Url(data) {
-    const base64 = data.replace(/-/g, '+').replace(/_/g, '/');
-    return Buffer.from(base64, 'base64').toString('utf-8');
-}
-// ── Address parsing utilities ──────────────────────────────────────
-/**
- * Parse a single "Name <email>" or bare "email" string.
- */
-function parseAddress(raw) {
-    const match = raw.match(/^(.+?)\s*<([^>]+)>$/);
-    if (match) {
-        return { name: match[1].replace(/^["']|["']$/g, '').trim(), email: match[2] };
-    }
-    return { email: raw.trim() };
-}
-/**
- * Parse a comma-separated list of addresses.
- */
-function parseAddressList(raw) {
-    if (!raw.trim())
-        return [];
-    const results = [];
-    let current = '';
-    let depth = 0;
-    for (const ch of raw) {
-        if (ch === '<')
-            depth++;
-        else if (ch === '>')
-            depth--;
-        else if (ch === ',' && depth === 0) {
-            if (current.trim())
-                results.push(parseAddress(current.trim()));
-            current = '';
-            continue;
-        }
-        current += ch;
-    }
-    if (current.trim())
-        results.push(parseAddress(current.trim()));
-    return results;
-}
-/**
- * Format an EmailAddress back into "Name <email>" string.
- */
-function formatAddress(addr) {
-    return addr.name ? `${addr.name} <${addr.email}>` : addr.email;
-}
-function errorMessage(err) {
-    return err instanceof Error ? err.message : String(err);
-}

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

@@ -1,48 +0,0 @@
-/**
- * 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

@@ -1,112 +0,0 @@
-/**
- * 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

@@ -1,78 +0,0 @@
-/** 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

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

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

@@ -1,16 +0,0 @@
-/**
- * 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

@@ -1,54 +0,0 @@
-/**
- * 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;
-}