botinabox 2.8.0 → 2.8.1

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

@@ -284,4 +284,86 @@ declare class GoogleDriveConnector implements Connector<DriveFileRecord> {
     private mapFile;
 }
 
-export { type CalendarAttendee, type CalendarConnectorOpts, type CalendarEventRecord, type DriveConnectorOpts, type DriveFileRecord, type DriveOwner, type EmailAddress, type EmailAttachment, type EmailRecord, type GmailConnectorOpts, GoogleCalendarConnector, type GoogleConnectorConfig, GoogleDriveConnector, GoogleGmailConnector, type GoogleOAuthConfig, type GoogleServiceAccountConfig, type GoogleTokens, createOAuth2Client, createServiceAccountClient, exchangeCode, getAuthUrl, loadTokens, refreshIfNeeded, saveTokens };
+/**
+ * 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 };

package/dist/connectors/google/index.js

@@ -474,15 +474,115 @@ var GoogleDriveConnector = class {
 function errorMessage2(err) {
   return err instanceof Error ? err.message : String(err);
 }
+
+// src/connectors/google/drive-read.ts
+var GOOGLE_NATIVE_PREFIX = "application/vnd.google-apps.";
+var GOOGLE_DOC = "application/vnd.google-apps.document";
+var GOOGLE_SHEET = "application/vnd.google-apps.spreadsheet";
+var GOOGLE_SLIDES = "application/vnd.google-apps.presentation";
+var GOOGLE_DRAWING = "application/vnd.google-apps.drawing";
+var EXPORT_MIME = {
+  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",
+  html: "text/html"
+};
+var EXPORT_EXTENSION = {
+  docx: "docx",
+  xlsx: "xlsx",
+  pptx: "pptx",
+  png: "png",
+  pdf: "pdf",
+  txt: "txt",
+  csv: "csv",
+  html: "html"
+};
+async function downloadDriveFile(drive, fileId) {
+  const metaRes = await drive.files.get({
+    fileId,
+    fields: "name,mimeType,size"
+  });
+  const { name: filename, mimeType, size } = metaRes.data;
+  const response = await drive.files.get(
+    { fileId, alt: "media" },
+    { responseType: "arraybuffer" }
+  );
+  const buffer = Buffer.from(response.data);
+  return {
+    buffer,
+    mimeType: mimeType ?? "application/octet-stream",
+    filename: filename ?? "document",
+    size: size ? parseInt(String(size), 10) : buffer.length
+  };
+}
+async function exportGoogleDoc(drive, fileId, exportAs) {
+  const metaRes = await drive.files.get({
+    fileId,
+    fields: "name,mimeType"
+  });
+  const { name: filename, mimeType } = metaRes.data;
+  if (!mimeType?.startsWith(GOOGLE_NATIVE_PREFIX)) {
+    throw new Error(
+      `Cannot export non-Google-native file. mimeType: ${mimeType}. Use downloadDriveFile instead.`
+    );
+  }
+  const targetMimeType = EXPORT_MIME[exportAs];
+  const response = await drive.files.export(
+    { fileId, mimeType: targetMimeType },
+    { responseType: "arraybuffer" }
+  );
+  const buffer = Buffer.from(response.data);
+  const extension = EXPORT_EXTENSION[exportAs];
+  let finalFilename = filename ?? "document";
+  if (!finalFilename.endsWith(`.${extension}`)) {
+    finalFilename = `${finalFilename}.${extension}`;
+  }
+  return {
+    buffer,
+    mimeType: targetMimeType,
+    filename: finalFilename,
+    size: buffer.length
+  };
+}
+async function readDriveFile(drive, fileId) {
+  const metaRes = await drive.files.get({
+    fileId,
+    fields: "name,mimeType,size"
+  });
+  const { mimeType } = metaRes.data;
+  if (mimeType?.startsWith(GOOGLE_NATIVE_PREFIX)) {
+    if (mimeType === GOOGLE_DOC) {
+      return exportGoogleDoc(drive, fileId, "docx");
+    }
+    if (mimeType === GOOGLE_SHEET) {
+      return exportGoogleDoc(drive, fileId, "xlsx");
+    }
+    if (mimeType === GOOGLE_SLIDES) {
+      return exportGoogleDoc(drive, fileId, "pptx");
+    }
+    if (mimeType === GOOGLE_DRAWING) {
+      return exportGoogleDoc(drive, fileId, "png");
+    }
+    throw new Error(`Unsupported Google-native type: ${mimeType}`);
+  }
+  return downloadDriveFile(drive, fileId);
+}
 export {
   GoogleCalendarConnector,
   GoogleDriveConnector,
   GoogleGmailConnector,
   createOAuth2Client,
   createServiceAccountClient,
+  downloadDriveFile,
   exchangeCode,
+  exportGoogleDoc,
   getAuthUrl,
   loadTokens,
+  readDriveFile,
   refreshIfNeeded,
   saveTokens
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "botinabox",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "description": "Bot in a Box — framework for building multi-agent bots",
   "type": "module",
   "main": "./dist/index.js",