botinabox 2.9.0 → 2.9.2

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

@@ -1,369 +1,10 @@
-import { C as ConnectorConfig, a as Connector, b as ConnectorMeta, A as AuthResult, S as SyncOptions, c as SyncResult, P as PushResult } from '../../connector-B4Mj0P1b.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 GoogleServiceAccountConfig {
-    /** Path to service account key JSON file */
-    keyFile?: string;
-    /** Inline service account credentials (alternative to keyFile) */
-    credentials?: {
-        client_email: string;
-        private_key: string;
-        project_id?: string;
-    };
-    /** Email of the user to impersonate via domain-wide delegation */
-    subject: string;
-}
-interface GoogleConnectorConfig extends ConnectorConfig {
-    /** Google account email */
-    account: string;
-    /** OAuth2 user auth (requires browser flow) */
-    oauth?: GoogleOAuthConfig;
-    /** Service account auth (headless, for cloud deployments) */
-    serviceAccount?: GoogleServiceAccountConfig;
-    scopes?: string[];
-}
-interface EmailAddress {
-    name?: string;
-    email: string;
-}
-interface EmailAttachment {
-    /** The Gmail attachment ID — can be used with users.messages.attachments.get */
-    attachmentId: string;
-    filename: string;
-    mimeType: string;
-    /** Size in bytes as reported by Gmail */
-    size: number;
-}
-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;
-    attachments: EmailAttachment[];
-}
-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;
-    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>;
-/**
- * Create an authenticated client using a service account with
- * domain-wide delegation (impersonation). No browser flow needed.
- */
-declare function createServiceAccountClient(config: GoogleServiceAccountConfig, scopes: string[]): Promise<OAuth2Client>;
-/**
- * Load persisted tokens via a generic getter callback.
- *
- * @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 (OAuth2 flow only). */
-    tokenLoader?: (key: string) => Promise<string | null>;
-    /** Persist tokens for a given account key (OAuth2 flow only). */
-    tokenSaver?: (key: string, value: string) => Promise<void>;
-}
-declare class GoogleGmailConnector implements Connector<EmailRecord> {
-    readonly id = "google-gmail";
-    readonly meta: ConnectorMeta;
-    private tokenLoader?;
-    private tokenSaver?;
-    private 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;
-    }>;
-    authenticate(codeProvider: (authUrl: string) => Promise<string>): Promise<AuthResult>;
-    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 (OAuth2 flow only). */
-    tokenLoader?: (key: string) => Promise<string | null>;
-    /** Persist tokens for a given account key (OAuth2 flow only). */
-    tokenSaver?: (key: string, value: string) => Promise<void>;
-}
-declare class GoogleCalendarConnector implements Connector<CalendarEventRecord> {
-    readonly id = "google-calendar";
-    readonly meta: ConnectorMeta;
-    private tokenLoader?;
-    private tokenSaver?;
-    private 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;
-    }>;
-    authenticate(codeProvider: (authUrl: string) => Promise<string>): Promise<AuthResult>;
-    sync(options?: SyncOptions): Promise<SyncResult<CalendarEventRecord>>;
-    /** Incremental sync using Calendar syncToken. */
-    private syncIncremental;
-    /** Full sync using timeMin. */
-    private syncFull;
-    private ensureConnected;
-    private mapEvent;
-}
-
-/**
- * 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;
-}
-
-/**
- * Google Drive file read primitives — download or export files to raw bytes.
- *
- * Signature-agnostic primitives that produce `{ buffer, mimeType, filename }`
- * tuples for use in attachment enrichment pipelines and other file consumers.
- */
-/**
- * Raw file bytes fetched from Google Drive, plus the metadata needed to
- * decide what to do with them (MIME type → extractor, filename → display).
- */
-interface DriveFileBytes {
-    buffer: Buffer;
-    mimeType: string;
-    filename: string;
-    /** Size in bytes as reported by the download response. */
-    size: number;
-}
-/**
- * Supported export target formats for Google-native file types
- * (Docs, Sheets, Slides, Drawings).
- */
-type GoogleDocExportAs = 'docx' | 'xlsx' | 'pptx' | 'png' | 'pdf' | 'txt' | 'csv' | 'html';
-/**
- * Download a binary Drive file as raw bytes.
- *
- * Use this for files uploaded to Drive in their native format (pdf, docx,
- * xlsx, pptx, jpg, png, mp4, etc.) — anything where the Drive `mimeType`
- * is NOT `application/vnd.google-apps.*`.
- *
- * For Google-native formats (Docs, Sheets, Slides, Drawings) use
- * `exportGoogleDoc` instead — `files.get` with `alt: 'media'` fails on
- * those with `fileNotDownloadable`.
- *
- * @param drive - googleapis `drive_v3.Drive` instance (kept as `any` to avoid hard type import)
- * @param fileId - Drive file ID
- * @returns Promise resolving to `DriveFileBytes` with buffer, mimeType, filename, and size
- */
-declare function downloadDriveFile(drive: any, fileId: string): Promise<DriveFileBytes>;
-/**
- * Export a Google-native document to a downloadable format.
- *
- * The `exportAs` argument picks the target MIME type:
- *   - docx → application/vnd.openxmlformats-officedocument.wordprocessingml.document
- *   - xlsx → application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
- *   - pptx → application/vnd.openxmlformats-officedocument.presentationml.presentation
- *   - png  → image/png
- *   - pdf  → application/pdf
- *   - txt  → text/plain
- *   - csv  → text/csv  (only valid for spreadsheets)
- *   - html → text/html
- *
- * Throws if the source file is not a Google-native type, or if the
- * requested export is not supported for that type (e.g., csv on a Doc).
- *
- * @param drive - googleapis `drive_v3.Drive` instance
- * @param fileId - Drive file ID
- * @param exportAs - Target export format
- * @returns Promise resolving to `DriveFileBytes` with exported content
- */
-declare function exportGoogleDoc(drive: any, fileId: string, exportAs: GoogleDocExportAs): Promise<DriveFileBytes>;
-/**
- * High-level dispatcher. Fetches file metadata, inspects the mimeType,
- * and picks `downloadDriveFile` (binary) or `exportGoogleDoc` (native)
- * automatically.
- *
- * Google-native → exported format mapping:
- *   - Docs       → docx
- *   - Sheets     → xlsx
- *   - Slides     → pptx
- *   - Drawings   → png
- *   - Scripts    → throws (not supported)
- *   - Forms/Site → throws (not supported)
- *
- * Consumers that want a different export target (e.g., gdoc → pdf for
- * Claude's native PDF reading) should call `exportGoogleDoc` directly.
- *
- * @param drive - googleapis `drive_v3.Drive` instance
- * @param fileId - Drive file ID
- * @returns Promise resolving to `DriveFileBytes` with automatically chosen format
- */
-declare function readDriveFile(drive: any, fileId: string): Promise<DriveFileBytes>;
-
-export { type CalendarAttendee, type CalendarConnectorOpts, type CalendarEventRecord, type DriveConnectorOpts, type DriveFileBytes, type DriveFileRecord, type DriveOwner, type EmailAddress, type EmailAttachment, type EmailRecord, type GmailConnectorOpts, GoogleCalendarConnector, type GoogleConnectorConfig, type GoogleDocExportAs, GoogleDriveConnector, GoogleGmailConnector, type GoogleOAuthConfig, type GoogleServiceAccountConfig, type GoogleTokens, createOAuth2Client, createServiceAccountClient, downloadDriveFile, exchangeCode, exportGoogleDoc, getAuthUrl, loadTokens, readDriveFile, refreshIfNeeded, saveTokens };
+/** Google connectors — Gmail, Calendar, and Drive. */
+export * from './types.js';
+export * from './oauth.js';
+export { GoogleGmailConnector } from './gmail-connector.js';
+export type { GmailConnectorOpts } from './gmail-connector.js';
+export { GoogleCalendarConnector } from './calendar-connector.js';
+export type { CalendarConnectorOpts } from './calendar-connector.js';
+export { GoogleDriveConnector } from './drive-connector.js';
+export type { DriveConnectorOpts } from './drive-connector.js';
+export { downloadDriveFile, exportGoogleDoc, readDriveFile, type DriveFileBytes, type GoogleDocExportAs, } from './drive-read.js';

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/types.d.ts

@@ -0,0 +1,110 @@
+/** 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 EmailAttachment {
+    /** The Gmail attachment ID — can be used with users.messages.attachments.get */
+    attachmentId: string;
+    filename: string;
+    mimeType: string;
+    /** Size in bytes as reported by Gmail */
+    size: number;
+}
+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;
+    attachments: EmailAttachment[];
+}
+export interface DriveOwner {
+    displayName: string;
+    emailAddress: string;
+}
+export 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;
+}
+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/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/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>;
+}