@flowuent-org/diagramming-core 1.1.0 → 1.1.2

package/packages/diagrams/src/lib/services/GoogleSheetsService.ts

@@ -0,0 +1,961 @@
+// Browser-compatible Google Sheets service
+// Note: This is a simplified version for browser environments
+// For production use, consider using a backend API to handle Google Sheets operations
+
+import * as XLSX from 'xlsx';
+import { saveAs } from 'file-saver';
+
+// GIS global injected by `https://accounts.google.com/gsi/client`
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+declare const google: any;
+
+// Mock Google Sheets API for browser environment
+const mockGoogleSheetsAPI = {
+  spreadsheets: {
+    values: {
+      update: async (params: any) => {
+        // Simulate API call delay
+        await new Promise((resolve) => setTimeout(resolve, 1000));
+        return {
+          data: {
+            updatedRows: params.requestBody.values.length,
+            updatedColumns: params.requestBody.values[0]?.length || 0,
+            updatedCells:
+              params.requestBody.values.length *
+              (params.requestBody.values[0]?.length || 0),
+          },
+        };
+      },
+      get: async (params: any) => {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return {
+          data: {
+            values: [],
+          },
+        };
+      },
+      clear: async (params: any) => {
+        await new Promise((resolve) => setTimeout(resolve, 500));
+        return {
+          data: {
+            clearedRange: params.range,
+          },
+        };
+      },
+    },
+  },
+};
+
+export interface GoogleSheetsConfig {
+  spreadsheetId: string;
+  sheetName: string;
+  range: string;
+  credentials: {
+    type: 'service-account' | 'oauth' | 'api-key';
+    serviceAccountKey?: string;
+    oauthToken?: string;
+    apiKey?: string;
+    clientEmail?: string;
+    privateKey?: string;
+    // OAuth client flow (Google Identity Services)
+    clientId?: string;
+    scopes?: string[];
+  };
+}
+
+export interface DataMapping {
+  headers: Array<{
+    column: string;
+    sourceField: string;
+    dataType: 'string' | 'number' | 'date' | 'boolean';
+  }>;
+  appendMode: boolean;
+  clearSheet: boolean;
+}
+
+export interface SheetsExportOptions {
+  emailRecipients?: string[];
+  fileName?: string;
+  exportFormat?: 'sheets' | 'excel';
+  includeHeaders?: boolean;
+}
+
+export interface SheetsResponse {
+  spreadsheetId: string;
+  sheetName: string;
+  range: string;
+  rowsAdded: number;
+  columnsMapped: number;
+  data: any[];
+  exportTime: string;
+  success: boolean;
+  spreadsheetUrl?: string;
+  downloadUrl?: string;
+  emailSent?: boolean;
+}
+
+export class GoogleSheetsService {
+  private sheets: any = null;
+  private auth: any = null;
+  private isBrowserEnvironment: boolean;
+  private accessToken: string | null = null;
+  private gisLoaded: boolean = false;
+  private hasRequestedConsent: boolean = false;
+  private requestedScopes: Set<string> = new Set();
+
+  constructor() {
+    // Detect if we're in a browser environment
+    this.isBrowserEnvironment = typeof window !== 'undefined';
+  }
+
+  /**
+   * Initialize Google Sheets API with authentication
+   * Note: In browser environment, this uses a mock API for demonstration
+   */
+  async initialize(config: GoogleSheetsConfig): Promise<void> {
+    try {
+      if (this.isBrowserEnvironment) {
+        // If OAuth credentials are provided, initialize Google Identity Services
+        if (
+          config.credentials?.type === 'oauth' &&
+          (config.credentials.clientEmail ||
+            config.credentials.oauthToken ||
+            config.credentials.clientId)
+        ) {
+          // Prefer OAuth clientId flow (GIS)
+          if (config.credentials.clientId) {
+            await this.ensureGisLoaded();
+            await this.requestAccessToken(
+              config.credentials.clientId,
+              config.credentials.scopes || [
+                'https://www.googleapis.com/auth/spreadsheets',
+              ],
+            );
+            this.sheets = 'rest';
+            this.auth = {
+              type: 'oauth',
+              clientId: config.credentials.clientId,
+              scopes: config.credentials.scopes || [
+                'https://www.googleapis.com/auth/spreadsheets',
+              ],
+            };
+            return;
+          }
+
+          // Fallback: if oauthToken is provided directly (e.g., injected), use it
+          if (config.credentials.oauthToken) {
+            this.accessToken = config.credentials.oauthToken;
+            this.sheets = 'rest';
+            this.auth = {
+              type: 'oauth',
+              clientId: config.credentials.clientId,
+              scopes: config.credentials.scopes || [
+                'https://www.googleapis.com/auth/spreadsheets',
+              ],
+            };
+            return;
+          }
+        }
+
+        // Browser environment without OAuth clientId – use mock API
+        console.log(
+          'Browser environment detected - using mock Google Sheets API',
+        );
+        this.sheets = mockGoogleSheetsAPI;
+        this.auth = { type: config.credentials?.type || 'mock' };
+        return;
+      }
+
+      // Node.js environment - would use real Google APIs
+      // This would require server-side implementation
+      throw new Error(
+        'Real Google Sheets API integration requires server-side implementation',
+      );
+    } catch (error) {
+      throw new Error(
+        `Failed to initialize Google Sheets API: ${error.message}`,
+      );
+    }
+  }
+
+  /**
+   * Ensure Google Identity Services script is loaded
+   */
+  private async ensureGisLoaded(): Promise<void> {
+    if (!this.isBrowserEnvironment) return;
+    if (this.gisLoaded) return;
+
+    await new Promise<void>((resolve, reject) => {
+      const existing = document.querySelector(
+        'script[src="https://accounts.google.com/gsi/client"]',
+      );
+      if (existing) {
+        this.gisLoaded = true;
+        resolve();
+        return;
+      }
+
+      const script = document.createElement('script');
+      script.src = 'https://accounts.google.com/gsi/client';
+      script.async = true;
+      script.defer = true;
+      script.onload = () => {
+        this.gisLoaded = true;
+        resolve();
+      };
+      script.onerror = () => reject(new Error('Failed to load GIS script'));
+      document.head.appendChild(script);
+    });
+  }
+
+  /**
+   * Request an OAuth access token using GIS token client
+   */
+  private async requestAccessToken(
+    clientId: string,
+    scopes: string[],
+    forceConsent: boolean = false,
+  ): Promise<string> {
+    if (!this.isBrowserEnvironment) {
+      throw new Error('OAuth is only available in browser environment');
+    }
+
+    await this.ensureGisLoaded();
+
+    const token = await new Promise<string>((resolve, reject) => {
+      try {
+        // @ts-ignore - google global injected by GIS
+        const tokenClient = google.accounts.oauth2.initTokenClient({
+          client_id: clientId,
+          scope: scopes.join(' '),
+          callback: (response: any) => {
+            // Handle both success and error shapes
+            if (response && response.access_token) {
+              this.hasRequestedConsent = true;
+              // Track that we've requested these scopes
+              scopes.forEach((s) => this.requestedScopes.add(s));
+              resolve(response.access_token);
+              return;
+            }
+            const err = response?.error || 'unknown_error';
+            const desc = response?.error_description || 'No description';
+            reject(new Error(`OAuth token error: ${err} - ${desc}`));
+          },
+        });
+
+        // First-time call must show consent; subsequent calls can be silent
+        tokenClient.requestAccessToken({
+          prompt: forceConsent
+            ? 'consent'
+            : this.hasRequestedConsent
+              ? ''
+              : 'consent',
+        });
+      } catch (e) {
+        reject(e);
+      }
+    });
+
+    this.accessToken = token;
+    // Persist clientId and union of scopes in auth cache for later scope upgrades
+    if (this.auth && typeof this.auth === 'object') {
+      (this.auth as any).clientId = clientId;
+      const union = Array.from(
+        new Set([...(this.auth.scopes || []), ...scopes]),
+      );
+      (this.auth as any).scopes = union;
+    }
+    return token;
+  }
+
+  /**
+   * Ensure the active token includes the given scopes. If not, request a new token with the union.
+   */
+  private async ensureScopes(requiredScopes: string[]): Promise<void> {
+    if (!this.isBrowserEnvironment) return;
+    if (!requiredScopes || requiredScopes.length === 0) return;
+    // If we don't have OAuth client flow, nothing to do
+    const clientId = (this as any).pendingClientId || undefined;
+    // We infer clientId from last initialize call by reading from DOM script params is not reliable.
+    // Instead, try to reuse the last known clientId from token creation by caching it in auth.
+    const authClientId: string | undefined =
+      (this.auth && this.auth.clientId) || undefined;
+    const effectiveClientId = authClientId || clientId;
+    if (!effectiveClientId) return;
+
+    const missing = requiredScopes.filter((s) => !this.requestedScopes.has(s));
+    if (missing.length === 0) return;
+
+    const union = Array.from(
+      new Set([...Array.from(this.requestedScopes), ...requiredScopes]),
+    );
+    await this.requestAccessToken(effectiveClientId, union, true);
+    if (this.auth && typeof this.auth === 'object') {
+      (this.auth as any).scopes = union;
+    }
+  }
+
+  /**
+   * Build a minimal RFC 2822 MIME message (plain text) and return base64url string.
+   */
+  private buildMimeMessage(params: {
+    from?: string;
+    to: string[];
+    subject?: string;
+    body?: string;
+  }): string {
+    const headers: string[] = [];
+    if (params.from) headers.push(`From: ${params.from}`);
+    headers.push(`To: ${params.to.join(', ')}`);
+    if (params.subject) headers.push(`Subject: ${params.subject}`);
+    headers.push('MIME-Version: 1.0');
+    headers.push('Content-Type: text/plain; charset=UTF-8');
+
+    const lines = [...headers, '', params.body || ''];
+    const raw = lines.join('\r\n');
+    return this.encodeBase64Url(raw);
+  }
+
+  /**
+   * Encode string to base64url (RFC 4648 §5), as required by Gmail API.
+   */
+  private encodeBase64Url(input: string): string {
+    // btoa works with Latin1; for UTF-8 we need to encode first
+    const utf8 = unescape(encodeURIComponent(input));
+    const b64 = btoa(utf8);
+    return b64.replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/g, '');
+  }
+
+  /**
+   * Attempt to send an email via Gmail API using the current OAuth token.
+   */
+  private async sendViaGmailApi(params: {
+    from?: string;
+    to: string[];
+    subject?: string;
+    message?: string;
+    spreadsheetUrl?: string;
+    // attachments are not implemented in this client-side example
+  }): Promise<boolean> {
+    const requiredScope = 'https://www.googleapis.com/auth/gmail.send';
+    await this.ensureScopes([requiredScope]);
+
+    if (!this.accessToken) {
+      throw new Error('Not authenticated to Google APIs');
+    }
+
+    const bodyParts: string[] = [];
+    if (params.message) bodyParts.push(params.message);
+    if (params.spreadsheetUrl)
+      bodyParts.push(`Spreadsheet: ${params.spreadsheetUrl}`);
+    const body = bodyParts.join('\n\n');
+
+    const raw = this.buildMimeMessage({
+      from: params.from,
+      to: params.to,
+      subject: params.subject || 'Automation Output',
+      body,
+    });
+
+    const res = await fetch(
+      'https://gmail.googleapis.com/gmail/v1/users/me/messages/send',
+      {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          Authorization: `Bearer ${this.accessToken}`,
+        },
+        body: JSON.stringify({ raw }),
+      },
+    );
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(
+        `Gmail send error ${res.status}: ${res.statusText} - ${text}`,
+      );
+    }
+    return true;
+  }
+
+  /**
+   * Helper: call Google Sheets REST API using fetch
+   */
+  private async apiFetch(
+    path: string,
+    options: {
+      method?: string;
+      body?: any;
+      params?: Record<string, string>;
+    } = {},
+  ): Promise<any> {
+    if (!this.accessToken) {
+      throw new Error('Not authenticated to Google APIs');
+    }
+
+    const base = 'https://sheets.googleapis.com/v4';
+    const url = new URL(base + path);
+    if (options.params) {
+      Object.entries(options.params).forEach(([k, v]) =>
+        url.searchParams.set(k, v),
+      );
+    }
+
+    const res = await fetch(url.toString(), {
+      method: options.method || 'GET',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.accessToken}`,
+      },
+      body: options.body ? JSON.stringify(options.body) : undefined,
+    });
+
+    if (!res.ok) {
+      const text = await res.text();
+      throw new Error(
+        `Google API error ${res.status}: ${res.statusText} - ${text}`,
+      );
+    }
+    return res.json();
+  }
+
+  /**
+   * Send email via Gmail API if authorized; fallback to mailto for simple cases
+   */
+  public async sendEmail(params: {
+    from?: string;
+    to: string[];
+    subject?: string;
+    message?: string;
+    spreadsheetUrl?: string;
+    attachExcelBlob?: Blob;
+    attachExcelFileName?: string;
+    disableUiFallback?: boolean;
+  }): Promise<boolean> {
+    // If we have OAuth token, try Gmail API (request scope on-demand)
+    const hasOauth = this.auth?.type === 'oauth' && this.accessToken;
+    if (hasOauth) {
+      try {
+        const sent = await this.sendViaGmailApi({
+          from: params.from,
+          to: params.to,
+          subject: params.subject,
+          message: params.message,
+          spreadsheetUrl: params.spreadsheetUrl,
+        });
+        if (sent) return true;
+      } catch (e) {
+        // Fall through to UI-based flow if API send fails (e.g., insufficient permissions)
+        console.warn(
+          'Gmail API send failed, falling back to UI:',
+          (e as any).message || e,
+        );
+      }
+    }
+
+    // Prefer: open Gmail compose in a new tab (more reliable than OS mailto handler)
+    if (this.isBrowserEnvironment && !params.disableUiFallback) {
+      const to = encodeURIComponent(params.to.join(','));
+      const subject = encodeURIComponent(params.subject || 'Automation Output');
+      const bodyParts: string[] = [];
+      if (params.message) bodyParts.push(params.message);
+      if (params.spreadsheetUrl)
+        bodyParts.push(`Spreadsheet: ${params.spreadsheetUrl}`);
+      const body = encodeURIComponent(bodyParts.join('\n\n'));
+
+      // Try Gmail compose
+      const gmailUrl = `https://mail.google.com/mail/?view=cm&fs=1&to=${to}&su=${subject}&body=${body}`;
+      const win = window.open(gmailUrl, '_blank', 'noopener,noreferrer');
+      if (win) {
+        return true;
+      }
+
+      // Fallback: OS handler via mailto
+      // Note: attachments are not supported via mailto; advise using Gmail scope for API send
+      const a = document.createElement('a');
+      a.href = `mailto:${to}?subject=${subject}&body=${body}`;
+      a.style.display = 'none';
+      document.body.appendChild(a);
+      a.click();
+      document.body.removeChild(a);
+
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Export data to Google Sheets
+   * Note: In browser environment, this simulates the export process
+   */
+  async exportToSheets(
+    data: any[],
+    config: GoogleSheetsConfig,
+    dataMapping: DataMapping,
+    options: SheetsExportOptions = {},
+  ): Promise<SheetsResponse> {
+    if (!this.sheets) {
+      throw new Error('Google Sheets API not initialized');
+    }
+
+    try {
+      // Prepare data for export
+      const mappedData = this.mapDataToColumns(data, dataMapping);
+      const includeHeaders = options.includeHeaders !== false;
+
+      // If using real OAuth flow, call REST API; otherwise, use mock behavior
+      const usingRest =
+        this.auth?.type === 'oauth' &&
+        this.accessToken &&
+        this.sheets === 'rest';
+
+      // Ensure spreadsheet exists when using REST
+      let spreadsheetId = config.spreadsheetId;
+      if (usingRest && !spreadsheetId) {
+        const created = await this.apiFetch('/spreadsheets', {
+          method: 'POST',
+          body: {
+            properties: { title: options.fileName || 'Automation Export' },
+            sheets: [
+              {
+                properties: { title: config.sheetName || 'Sheet1' },
+              },
+            ],
+          },
+        });
+        spreadsheetId = created.spreadsheetId;
+        config.spreadsheetId = spreadsheetId;
+      }
+
+      // Ensure sheet exists
+      if (usingRest && spreadsheetId && config.sheetName) {
+        const meta = await this.apiFetch(`/spreadsheets/${spreadsheetId}`, {
+          params: { fields: 'sheets.properties.title' },
+        });
+        const hasSheet = (meta.sheets || []).some(
+          (s: any) => s.properties && s.properties.title === config.sheetName,
+        );
+        if (!hasSheet) {
+          await this.apiFetch(`/spreadsheets/${spreadsheetId}:batchUpdate`, {
+            method: 'POST',
+            body: {
+              requests: [
+                {
+                  addSheet: { properties: { title: config.sheetName } },
+                },
+              ],
+            },
+          });
+        }
+      }
+
+      // Clear sheet if requested
+      if (dataMapping.clearSheet) {
+        await this.clearSheet(config);
+      }
+
+      // Prepare range for writing (account for header row if included)
+      const totalRows = mappedData.length + (includeHeaders ? 1 : 0);
+      const range = this.prepareRange(config, dataMapping, totalRows);
+
+      // Prepare values array
+      const values = this.prepareValues(
+        mappedData,
+        dataMapping,
+        includeHeaders,
+      );
+
+      if (usingRest) {
+        await this.apiFetch(
+          `/spreadsheets/${config.spreadsheetId}/values/${encodeURIComponent(
+            range,
+          )}`,
+          {
+            method: 'PUT',
+            params: { valueInputOption: 'RAW' },
+            body: { values },
+          },
+        );
+      } else {
+        // Mock behavior
+        await this.sheets.spreadsheets.values.update({
+          spreadsheetId: config.spreadsheetId,
+          range: range,
+          valueInputOption: 'RAW',
+          requestBody: { values },
+        });
+      }
+
+      // Get spreadsheet URL
+      const spreadsheetUrl = `https://docs.google.com/spreadsheets/d/${config.spreadsheetId}`;
+
+      // Send email if recipients provided
+      let emailSent = false;
+      if (options.emailRecipients && options.emailRecipients.length > 0) {
+        emailSent = await this.sendEmailNotification(
+          options.emailRecipients,
+          spreadsheetUrl,
+          options.fileName || 'Google Sheets Export',
+        );
+      }
+
+      return {
+        spreadsheetId: config.spreadsheetId,
+        sheetName: config.sheetName,
+        range: range,
+        rowsAdded: mappedData.length,
+        columnsMapped: dataMapping.headers.length,
+        data: mappedData,
+        exportTime: new Date().toISOString(),
+        success: true,
+        spreadsheetUrl,
+        emailSent,
+      };
+    } catch (error) {
+      throw new Error(`Failed to export to Google Sheets: ${error.message}`);
+    }
+  }
+
+  /**
+   * Export data to Excel file and download
+   */
+  async exportToExcel(
+    data: any[],
+    dataMapping: DataMapping,
+    options: SheetsExportOptions = {},
+  ): Promise<SheetsResponse> {
+    try {
+      // Prepare data for export
+      const mappedData = this.mapDataToColumns(data, dataMapping);
+
+      // Create workbook
+      const wb = XLSX.utils.book_new();
+
+      // Prepare worksheet data
+      const wsData = this.prepareExcelData(
+        mappedData,
+        dataMapping,
+        options.includeHeaders !== false,
+      );
+
+      // Create worksheet
+      const ws = XLSX.utils.aoa_to_sheet(wsData);
+
+      // Add worksheet to workbook
+      XLSX.utils.book_append_sheet(wb, ws, 'Sheet1');
+
+      // Generate file name
+      const fileName =
+        options.fileName ||
+        `export_${new Date().toISOString().split('T')[0]}.xlsx`;
+
+      // Save file
+      const excelBuffer = XLSX.write(wb, { bookType: 'xlsx', type: 'array' });
+      const blob = new Blob([excelBuffer], {
+        type: 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+      });
+      saveAs(blob, fileName);
+
+      // Send email if recipients provided
+      let emailSent = false;
+      if (options.emailRecipients && options.emailRecipients.length > 0) {
+        emailSent = await this.sendEmailWithAttachment(
+          options.emailRecipients,
+          blob,
+          fileName,
+        );
+      }
+
+      return {
+        spreadsheetId: '',
+        sheetName: 'Sheet1',
+        range: '',
+        rowsAdded: mappedData.length,
+        columnsMapped: dataMapping.headers.length,
+        data: mappedData,
+        exportTime: new Date().toISOString(),
+        success: true,
+        downloadUrl: URL.createObjectURL(blob),
+        emailSent,
+      };
+    } catch (error) {
+      throw new Error(`Failed to export to Excel: ${error.message}`);
+    }
+  }
+
+  /**
+   * Map data according to column configuration
+   */
+  private mapDataToColumns(data: any[], dataMapping: DataMapping): any[] {
+    return data.map((item: any) => {
+      const row: any = {};
+      dataMapping.headers.forEach((header) => {
+        const value = this.getNestedValue(item, header.sourceField);
+        row[header.column] = this.formatValueForSheets(value, header.dataType);
+      });
+      return row;
+    });
+  }
+
+  /**
+   * Get nested value from object using dot notation
+   */
+  private getNestedValue(obj: any, path: string): any {
+    return path.split('.').reduce((current, key) => current?.[key], obj);
+  }
+
+  /**
+   * Format value according to data type
+   */
+  private formatValueForSheets(value: any, dataType: string): any {
+    if (value === null || value === undefined) {
+      return '';
+    }
+
+    switch (dataType) {
+      case 'number':
+        return typeof value === 'number' ? value : parseFloat(value) || 0;
+      case 'date':
+        return value instanceof Date
+          ? value.toISOString().split('T')[0]
+          : value;
+      case 'boolean':
+        return Boolean(value);
+      case 'string':
+      default:
+        return String(value);
+    }
+  }
+
+  /**
+   * Prepare range for writing data
+   */
+  private prepareRange(
+    config: GoogleSheetsConfig,
+    dataMapping: DataMapping,
+    rowCount: number,
+  ): string {
+    const startColumn = dataMapping.headers[0]?.column || 'A';
+    const endColumn =
+      dataMapping.headers[dataMapping.headers.length - 1]?.column || 'Z';
+    const startRow = dataMapping.clearSheet ? 1 : 1; // Simplified for browser
+    const endRow = startRow + rowCount - 1;
+
+    return `${config.sheetName}!${startColumn}${startRow}:${endColumn}${endRow}`;
+  }
+
+  /**
+   * Clear sheet content
+   */
+  private async clearSheet(config: GoogleSheetsConfig): Promise<void> {
+    if (!this.sheets) return;
+
+    try {
+      const usingRest =
+        this.auth?.type === 'oauth' &&
+        this.accessToken &&
+        this.sheets === 'rest';
+      const range = `${config.sheetName}!A:Z`;
+      if (usingRest) {
+        await this.apiFetch(
+          `/spreadsheets/${config.spreadsheetId}/values/${encodeURIComponent(
+            range,
+          )}:clear`,
+          { method: 'POST' },
+        );
+      } else {
+        await this.sheets.spreadsheets.values.clear({
+          spreadsheetId: config.spreadsheetId,
+          range,
+        });
+      }
+    } catch (error) {
+      console.warn('Failed to clear sheet:', (error as any).message || error);
+    }
+  }
+
+  /**
+   * Prepare values array for Google Sheets API
+   */
+  private prepareValues(
+    mappedData: any[],
+    dataMapping: DataMapping,
+    includeHeaders: boolean,
+  ): any[][] {
+    const values: any[][] = [];
+
+    // Add headers if requested
+    if (includeHeaders && dataMapping.headers.length > 0) {
+      const headers = dataMapping.headers.map((h) => h.column);
+      values.push(headers);
+    }
+
+    // Add data rows
+    mappedData.forEach((row) => {
+      const rowValues = dataMapping.headers.map(
+        (header) => row[header.column] || '',
+      );
+      values.push(rowValues);
+    });
+
+    return values;
+  }
+
+  /**
+   * Prepare data for Excel export
+   */
+  private prepareExcelData(
+    mappedData: any[],
+    dataMapping: DataMapping,
+    includeHeaders: boolean,
+  ): any[][] {
+    const data: any[][] = [];
+
+    // Add headers if requested
+    if (includeHeaders && dataMapping.headers.length > 0) {
+      const headers = dataMapping.headers.map((h) => h.column);
+      data.push(headers);
+    }
+
+    // Add data rows
+    mappedData.forEach((row) => {
+      const rowValues = dataMapping.headers.map(
+        (header) => row[header.column] || '',
+      );
+      data.push(rowValues);
+    });
+
+    return data;
+  }
+
+  /**
+   * Send email notification with spreadsheet link
+   */
+  private async sendEmailNotification(
+    recipients: string[],
+    spreadsheetUrl: string,
+    fileName: string,
+  ): Promise<boolean> {
+    try {
+      // In browser environment, we'll simulate email sending
+      console.log(
+        `📧 Email notification would be sent to: ${recipients.join(', ')}`,
+      );
+      console.log(`📊 Spreadsheet URL: ${spreadsheetUrl}`);
+      console.log(`📁 File: ${fileName}`);
+
+      // Show a browser notification or alert
+      if (this.isBrowserEnvironment && 'Notification' in window) {
+        if (Notification.permission === 'granted') {
+          new Notification('Google Sheets Export', {
+            body: `Data exported successfully! Sent to ${recipients.length} recipient(s).`,
+            icon: '/favicon.ico',
+          });
+        }
+      }
+
+      return true;
+    } catch (error) {
+      console.error('Failed to send email notification:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Send email with Excel attachment
+   */
+  private async sendEmailWithAttachment(
+    recipients: string[],
+    fileBlob: Blob,
+    fileName: string,
+  ): Promise<boolean> {
+    try {
+      // In browser environment, we'll simulate email sending
+      console.log(
+        `📧 Email with attachment would be sent to: ${recipients.join(', ')}`,
+      );
+      console.log(`📎 Attachment: ${fileName}`);
+      console.log(`📊 File size: ${(fileBlob.size / 1024).toFixed(2)} KB`);
+
+      // Show a browser notification
+      if (this.isBrowserEnvironment && 'Notification' in window) {
+        if (Notification.permission === 'granted') {
+          new Notification('Excel Export', {
+            body: `Excel file "${fileName}" exported successfully! Sent to ${recipients.length} recipient(s).`,
+            icon: '/favicon.ico',
+          });
+        }
+      }
+
+      return true;
+    } catch (error) {
+      console.error('Failed to send email with attachment:', error);
+      return false;
+    }
+  }
+
+  /**
+   * Validate configuration
+   */
+  validateConfig(config: GoogleSheetsConfig): {
+    valid: boolean;
+    errors: string[];
+  } {
+    const errors: string[] = [];
+
+    if (!config.spreadsheetId) {
+      // Allow creating a new spreadsheet when using OAuth clientId
+      if (
+        !(config.credentials?.type === 'oauth' && config.credentials.clientId)
+      ) {
+        errors.push(
+          'Spreadsheet ID is required (or provide OAuth clientId to create a new one)',
+        );
+      }
+    }
+
+    if (!config.sheetName) {
+      errors.push('Sheet name is required');
+    }
+
+    if (!config.credentials) {
+      errors.push('Credentials are required');
+    } else {
+      if (config.credentials.type === 'service-account') {
+        if (
+          !config.credentials.serviceAccountKey &&
+          !config.credentials.clientEmail
+        ) {
+          errors.push('Service account key or client email is required');
+        }
+        if (
+          !config.credentials.serviceAccountKey &&
+          !config.credentials.privateKey
+        ) {
+          errors.push('Service account key or private key is required');
+        }
+      } else if (config.credentials.type === 'api-key') {
+        if (!config.credentials.apiKey) {
+          errors.push('API key is required');
+        }
+      } else if (config.credentials.type === 'oauth') {
+        // Accept either a provided token or clientId for GIS
+        if (!config.credentials.oauthToken && !config.credentials.clientId) {
+          errors.push('OAuth clientId or oauthToken is required');
+        }
+        if (config.credentials.clientId && !config.credentials.scopes) {
+          // Provide default scope if not present
+          config.credentials.scopes = [
+            'https://www.googleapis.com/auth/spreadsheets',
+          ];
+        }
+      }
+    }
+
+    return {
+      valid: errors.length === 0,
+      errors,
+    };
+  }
+}