@divizend/scratch-core 1.0.0

package/gsuite/core/GSuite.ts

@@ -0,0 +1,237 @@
+/**
+ * GSuite - Google Workspace Integration Manager
+ *
+ * The GSuite class manages integration with Google Workspace (formerly G Suite)
+ * services including Gmail, Google Drive, Google Sheets, and Google Docs.
+ *
+ * This class handles:
+ * - Multi-organization Google Workspace setup
+ * - Service account authentication and JWT management
+ * - User directory management and domain validation
+ * - Centralized access to all Google Workspace APIs
+ *
+ * The system supports multiple organizations, each with their own service account
+ * credentials, enabling enterprise-scale deployments with proper isolation.
+ *
+ * @class GSuite
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { JWT } from "google-auth-library";
+import { admin_directory_v1 } from "googleapis";
+import { GSuiteOrgConfig, GSuiteUser, Universe } from "../..";
+import { parseEnvGroup } from "../../core/Env";
+
+export class GSuite {
+  /**
+   * Creates a new GSuite instance
+   *
+   * @param universe - Reference to the central Universe instance
+   * @param orgConfigs - Configuration for each organization
+   * @param usersDirectory - Cached user directory data for performance
+   */
+  constructor(
+    private readonly universe: Universe,
+    private readonly orgConfigs: { [org: string]: GSuiteOrgConfig },
+    private readonly usersDirectory: {
+      [email: string]: admin_directory_v1.Schema$User;
+    }
+  ) {}
+
+  /**
+   * Constructs and initializes a GSuite instance
+   *
+   * This factory method performs the following initialization steps:
+   * 1. Parses environment variables for GCP credentials
+   * 2. Creates JWT authentication functions for each organization
+   * 3. Fetches domain and user information for each organization
+   * 4. Builds the user directory cache for efficient lookups
+   *
+   * Environment Variables Required:
+   * - GCP_CLIENT_EMAIL_<identifier>: Service account email
+   * - GCP_PRIVATE_KEY_<identifier>: Service account private key
+   * - GCP_ADMIN_USER_<identifier>: Admin user email for the organization
+   *
+   * @param universe - Reference to the central Universe instance
+   * @returns Promise<GSuite> - Fully initialized GSuite instance
+   * @throws Error if required credentials are missing or invalid
+   */
+  static async construct(universe: Universe) {
+    // Parse environment variables grouped by organization identifier
+    const gcpCreds = parseEnvGroup<
+      {
+        clientEmail: string;
+        privateKey: string;
+        adminUser: string;
+      }
+    >(
+      ["GCP_CLIENT_EMAIL_", "GCP_PRIVATE_KEY_", "GCP_ADMIN_USER_"],
+      {
+        propertyMap: {
+          "GCP_CLIENT_EMAIL_": "clientEmail",
+          "GCP_PRIVATE_KEY_": "privateKey",
+          "GCP_ADMIN_USER_": "adminUser",
+        },
+        identifierExtractor: (key: string) => {
+          // For "GCP_CLIENT_EMAIL_ORG1", split by "_" gives ["GCP", "CLIENT", "EMAIL", "ORG1"]
+          // We want the 4th segment (index 3), lowercased
+          const parts = key.split("_");
+          return parts[3]?.toLowerCase() || "";
+        },
+        errorMessage:
+          "No GCP credentials found. Please set GCP_CLIENT_EMAIL_<identifier>, GCP_PRIVATE_KEY_<identifier> and GCP_ADMIN_USER_<identifier> environment variables.",
+      }
+      );
+
+    const orgConfigs: {
+      [org: string]: GSuiteOrgConfig;
+    } = {};
+
+    const rawAuths: { [org: string]: (subject: string) => JWT } = {};
+
+    // Create JWT authentication functions for each organization
+    for (const [identifier, creds] of Object.entries(gcpCreds)) {
+      if (!creds.clientEmail || !creds.privateKey || !creds.adminUser) {
+        throw new Error(
+          `Missing GCP credentials for ${identifier}. Please set GCP_CLIENT_EMAIL_${identifier}, GCP_PRIVATE_KEY_${identifier} and GCP_ADMIN_USER_${identifier} environment variables.`
+        );
+      }
+
+      // Create JWT authentication with required scopes
+      rawAuths[identifier] = (subject: string) =>
+        new JWT({
+          email: creds.clientEmail!,
+          key: creds.privateKey!,
+          scopes: [
+            "https://www.googleapis.com/auth/gmail.readonly",
+            "https://www.googleapis.com/auth/gmail.send",
+            "https://www.googleapis.com/auth/gmail.modify",
+            "https://www.googleapis.com/auth/gmail.settings.sharing",
+            "https://www.googleapis.com/auth/admin.directory.user.readonly",
+            "https://www.googleapis.com/auth/admin.directory.domain.readonly",
+            "https://www.googleapis.com/auth/spreadsheets",
+            "https://www.googleapis.com/auth/drive",
+            "https://www.googleapis.com/auth/documents",
+          ],
+          subject,
+        });
+    }
+
+    // Initialize organization configurations and user directory
+    const usersDirectory: { [email: string]: admin_directory_v1.Schema$User } =
+      {};
+
+    for (const [identifier, rawAuth] of Object.entries(rawAuths)) {
+      const adminUser = gcpCreds[identifier]!.adminUser!;
+
+      // Create admin user instance and fetch organization data
+      const admin = new GSuiteUser(
+        universe,
+        rawAuth(adminUser),
+        usersDirectory[adminUser]!
+      ).admin();
+
+      // Fetch domains for the organization
+      const domains = await admin.getDomains();
+      orgConfigs[identifier] = new GSuiteOrgConfig(rawAuth, domains, adminUser);
+
+      console.warn(
+        `${identifier} has ${orgConfigs[identifier].domains.length} domains`
+      );
+
+      // Fetch and cache user directory information
+      const users = await admin.getUsers();
+      for (const user of users) {
+        usersDirectory[user.primaryEmail!] = user;
+      }
+
+      console.warn(`${identifier} has ${users.length} users`);
+      for (const user of users) {
+        console.log(user.primaryEmail);
+      }
+    }
+
+    return new GSuite(universe, orgConfigs, usersDirectory);
+  }
+
+  /**
+   * Creates a GSuiteUser instance for the specified email address
+   *
+   * This method:
+   * 1. Determines which organization the user belongs to based on email domain
+   * 2. Retrieves the appropriate authentication configuration
+   * 3. Fetches user directory data for the specified user
+   * 4. Returns a configured GSuiteUser instance with proper permissions
+   *
+   * @param email - The user's email address
+   * @returns GSuiteUser instance configured for the specified user
+   * @throws Error if the user's domain is not found or user is not in directory
+   */
+  user(email: string): GSuiteUser {
+    // Find the organization configuration based on email domain
+    const emailDomain = email.split("@")[1]!;
+    const orgConfig = Object.values(this.orgConfigs).find((orgConfig) =>
+      orgConfig.domains.some((domain) => domain.domainName === emailDomain)
+    );
+
+    if (!orgConfig) {
+      throw new Error(`Domain of ${email} not found in any organization`);
+    }
+
+    // Retrieve user directory data for authentication and permissions
+    const directoryData = this.usersDirectory[email];
+    if (!directoryData) {
+      throw new Error(`User ${email} not found in directory`);
+    }
+
+    // Create and return configured user instance
+    return new GSuiteUser(
+      this.universe,
+      orgConfig.getAuth(email),
+      directoryData
+    );
+  }
+
+  /**
+   * Checks the health of the GSuite service
+   * Verifies connectivity by attempting to fetch domains from the first organization
+   *
+   * @returns Promise<{ status: string; message: string; connected: boolean; organization?: string }>
+   */
+  async getHealth(): Promise<{
+    status: string;
+    message: string;
+    connected: boolean;
+    organization?: string;
+  }> {
+    try {
+      if (!this.orgConfigs || Object.keys(this.orgConfigs).length === 0) {
+        return {
+          status: "error",
+          message: "No GSuite organizations configured",
+          connected: false,
+        };
+      }
+
+      const firstOrg = Object.keys(this.orgConfigs)[0];
+      const orgConfig = this.orgConfigs[firstOrg];
+      const gsuiteUser = this.user(orgConfig.adminUser);
+      const admin = gsuiteUser.admin();
+      await admin.getDomains();
+
+      return {
+        status: "ok",
+        message: "Google APIs connection active",
+        connected: true,
+        organization: firstOrg,
+      };
+    } catch (error) {
+      return {
+        status: "error",
+        message: error instanceof Error ? error.message : "Unknown error",
+        connected: false,
+      };
+    }
+  }
+}

package/gsuite/core/GSuiteAdmin.ts

@@ -0,0 +1,81 @@
+/**
+ * GSuiteAdmin - Google Workspace Administrative Operations
+ *
+ * The GSuiteAdmin class provides administrative access to Google Workspace
+ * organizational settings, including domain management and user directory operations.
+ *
+ * This class handles:
+ * - Domain listing and validation for multi-tenant organizations
+ * - User directory queries for authentication and permissions
+ * - Administrative operations that require elevated privileges
+ *
+ * All operations are performed using the Google Admin SDK Directory API
+ * with the authenticated user's administrative credentials.
+ *
+ * @class GSuiteAdmin
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { google, admin_directory_v1 } from "googleapis";
+import { JWT } from "google-auth-library";
+import { Universe } from "../..";
+
+export class GSuiteAdmin {
+  /** Google Admin SDK Directory API client instance */
+  private admin: admin_directory_v1.Admin;
+
+  /**
+   * Creates a new GSuiteAdmin instance
+   *
+   * @param universe - Reference to the central Universe instance
+   * @param auth - JWT authentication with administrative privileges
+   */
+  constructor(private readonly universe: Universe, private auth: JWT) {
+    this.admin = google.admin({ version: "directory_v1", auth: this.auth });
+  }
+
+  /**
+   * Retrieves all domains associated with the organization
+   *
+   * This method queries the Google Admin SDK to list all domains
+   * that belong to the authenticated user's organization. This is
+   * essential for multi-domain organizations and user authentication.
+   *
+   * @returns Promise<admin_directory_v1.Schema$Domains[]> - Array of domain objects
+   * @throws Error if no domains are found or the API call fails
+   */
+  async getDomains(): Promise<admin_directory_v1.Schema$Domains[]> {
+    const response = await this.admin.domains.list({
+      customer: "my_customer",
+    });
+
+    if (!response.data.domains || response.data.domains.length === 0) {
+      throw new Error("No domains found");
+    }
+
+    return response.data.domains;
+  }
+
+  /**
+   * Retrieves all users in the organization
+   *
+   * This method queries the Google Admin SDK to list all users
+   * that belong to the authenticated user's organization. The user
+   * list is used for authentication, permissions, and directory lookups.
+   *
+   * @returns Promise<admin_directory_v1.Schema$User[]> - Array of user objects
+   * @throws Error if no users are found or the API call fails
+   */
+  async getUsers(): Promise<admin_directory_v1.Schema$User[]> {
+    const response = await this.admin.users.list({
+      customer: "my_customer",
+    });
+
+    if (!response.data.users || response.data.users.length === 0) {
+      throw new Error("No users found");
+    }
+
+    return response.data.users;
+  }
+}

package/gsuite/core/GSuiteOrgConfig.ts

@@ -0,0 +1,47 @@
+/**
+ * GSuiteOrgConfig - Organization Configuration Container
+ *
+ * The GSuiteOrgConfig class holds configuration information for a specific
+ * Google Workspace organization, including authentication details, domain
+ * information, and administrative user settings.
+ *
+ * This class serves as a data container that encapsulates all the necessary
+ * information to authenticate and operate within a specific organization's
+ * Google Workspace environment.
+ *
+ * @class GSuiteOrgConfig
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { JWT } from "google-auth-library";
+import { admin_directory_v1 } from "googleapis";
+
+export class GSuiteOrgConfig {
+  /**
+   * Creates a new GSuiteOrgConfig instance
+   *
+   * @param jwt - Function that creates JWT instances for organization users
+   * @param domains - Array of domains associated with the organization
+   * @param adminUser - Email address of the administrative user for the organization
+   */
+  constructor(
+    public readonly jwt: (subject: string) => JWT,
+    public readonly domains: admin_directory_v1.Schema$Domains[],
+    public readonly adminUser: string
+  ) {}
+
+  /**
+   * Creates a JWT authentication instance for a specific user
+   *
+   * This method uses the organization's service account credentials
+   * to create a JWT token that can impersonate the specified user
+   * within the organization's Google Workspace environment.
+   *
+   * @param subject - The email address of the user to authenticate as
+   * @returns JWT instance configured for the specified user
+   */
+  getAuth(subject: string): JWT {
+    return this.jwt(subject);
+  }
+}

package/gsuite/core/GSuiteUser.ts

@@ -0,0 +1,115 @@
+/**
+ * GSuiteUser - Google Workspace Service Facade
+ *
+ * The GSuiteUser class provides a unified interface for accessing all Google Workspace
+ * services on behalf of a specific user. It acts as a facade that simplifies access
+ * to Gmail, Google Drive, Google Sheets, Google Docs, and administrative functions.
+ *
+ * Each GSuiteUser instance is configured with:
+ * - JWT authentication for the specific user
+ * - User directory data for permissions and metadata
+ * - Access to all Google Workspace APIs through service-specific classes
+ *
+ * This class implements the Facade pattern, hiding the complexity of individual
+ * Google Workspace APIs behind a simple, consistent interface.
+ *
+ * @class GSuiteUser
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { JWT } from "google-auth-library";
+import { admin_directory_v1 } from "googleapis";
+import {
+  Documents,
+  Drive,
+  GSuiteAdmin,
+  Gmail,
+  Spreadsheets,
+  Universe,
+} from "../..";
+
+export class GSuiteUser {
+  /**
+   * Creates a new GSuiteUser instance
+   *
+   * @param universe - Reference to the central Universe instance
+   * @param auth - JWT authentication for the specific user
+   * @param directoryData - User directory information and metadata
+   */
+  constructor(
+    private readonly universe: Universe,
+    public readonly auth: JWT,
+    public readonly directoryData: admin_directory_v1.Schema$User
+  ) {}
+
+  /**
+   * Provides access to Google Workspace administrative functions
+   *
+   * Returns a GSuiteAdmin instance that can perform administrative
+   * operations like managing users, domains, and organizational settings.
+   *
+   * @returns GSuiteAdmin instance for administrative operations
+   */
+  admin(): GSuiteAdmin {
+    return new GSuiteAdmin(this.universe, this.auth);
+  }
+
+  /**
+   * Provides access to Google Docs services
+   *
+   * Returns a Documents instance that can create, read, update,
+   * and delete Google Docs documents programmatically.
+   *
+   * @returns Documents instance for Google Docs operations
+   */
+  documents(): Documents {
+    return new Documents(this.universe, this.auth);
+  }
+
+  /**
+   * Provides access to Google Drive services
+   *
+   * Returns a Drive instance that can manage files and folders,
+   * handle file uploads/downloads, and manage sharing permissions.
+   *
+   * @returns Drive instance for Google Drive operations
+   */
+  drive(): Drive {
+    return new Drive(this.universe, this.auth);
+  }
+
+  /**
+   * Provides access to Gmail services
+   *
+   * Returns a Gmail instance that can read emails, send messages,
+   * manage labels, and handle email processing workflows.
+   *
+   * @returns Gmail instance for Gmail operations
+   */
+  gmail(): Gmail {
+    return new Gmail(this.universe, this.auth);
+  }
+
+  /**
+   * Provides access to Google Sheets services
+   *
+   * Returns a Spreadsheets instance that can read/write spreadsheet
+   * data, manage sheets, and perform data analysis operations.
+   *
+   * @returns Spreadsheets instance for Google Sheets operations
+   */
+  spreadsheets(): Spreadsheets {
+    return new Spreadsheets(this.universe, this.auth);
+  }
+
+  /**
+   * The email address of the authenticated user
+   *
+   * This property provides convenient access to the user's email
+   * address for use in API calls and logging.
+   */
+  get email() {
+    return this.auth.subject;
+  }
+}

package/gsuite/core/index.ts

@@ -0,0 +1,21 @@
+/**
+ * GSuite Core Module - Foundation Components
+ *
+ * This module contains the core building blocks for Google Workspace integration:
+ * - GSuite: Main integration manager for multi-organization setups
+ * - GSuiteUser: User-specific service access facade
+ * - GSuiteAdmin: Administrative operations and directory management
+ * - GSuiteOrgConfig: Organization configuration and authentication
+ *
+ * These components provide the foundation for all Google Workspace services
+ * including authentication, user management, and organizational structure.
+ *
+ * @module GSuiteCore
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export * from "./GSuite";
+export * from "./GSuiteUser";
+export * from "./GSuiteAdmin";
+export * from "./GSuiteOrgConfig";

package/gsuite/documents/Document.ts

@@ -0,0 +1,173 @@
+/**
+ * Document - Individual Google Document Operations
+ *
+ * The Document class represents a single Google Docs document and provides
+ * methods for content manipulation, placeholder replacement, and document
+ * editing operations.
+ *
+ * Key Features:
+ * - Document metadata and properties access
+ * - Placeholder text replacement and customization
+ * - Batch update operations for efficiency
+ * - Integration with Google Docs API
+ *
+ * This class enables automated document generation workflows by providing
+ * programmatic access to document content and editing capabilities.
+ *
+ * @class Document
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { docs_v1 } from "googleapis";
+import { Documents } from ".";
+import TurndownService from "turndown";
+
+/**
+ * Mapping of placeholder keys to replacement values
+ *
+ * This type defines the structure for placeholder replacement operations,
+ * where keys represent placeholder text (e.g., "{{DATE}}") and values
+ * represent the content to replace them with.
+ */
+export type DocumentPlaceholderReplacements = { [key: string]: string };
+
+export class Document {
+  /**
+   * Creates a new Document instance
+   *
+   * @param docs - Reference to the Documents service instance
+   * @param document - Raw Google Docs API document data
+   */
+  constructor(
+    private readonly docs: Documents,
+    public readonly document: docs_v1.Schema$Document
+  ) {}
+
+  /**
+   * Constructs a Document instance from a document ID
+   *
+   * This factory method fetches the document content from Google Docs
+   * and creates a Document instance ready for operations.
+   *
+   * @param docs - Documents service instance
+   * @param documentId - Google Docs document ID
+   * @returns Promise<Document> - Initialized document instance
+   */
+  static async construct(docs: Documents, documentId: string) {
+    const document = await docs.docs.documents.get({ documentId });
+    return new Document(docs, document.data);
+  }
+
+  /**
+   * Gets the unique identifier for this document
+   *
+   * The document ID is used for all Google Docs API operations
+   * and can be used to reference this document in other services.
+   */
+  get id(): string {
+    return this.document.documentId!;
+  }
+
+  /**
+   * Replaces placeholder text in the document with specified values
+   *
+   * This method performs batch replacement of placeholder text (e.g., "{{DATE}}")
+   * with actual values. It's commonly used in template-based document
+   * generation workflows to customize document content automatically.
+   *
+   * The method uses the Google Docs batchUpdate API for efficiency,
+   * processing all replacements in a single API call.
+   *
+   * @param replacements - Object mapping placeholder keys to replacement values
+   * @returns Promise containing the batch update response
+   * @throws Error if the batch update operation fails
+   */
+  async replacePlaceholders(replacements: DocumentPlaceholderReplacements) {
+    return this.docs.docs.documents.batchUpdate({
+      documentId: this.id,
+      requestBody: {
+        requests: Object.entries(replacements).map(([key, value]) => ({
+          replaceAllText: {
+            containsText: { text: `{{${key}}}`, matchCase: true },
+            replaceText: value,
+          },
+        })),
+      },
+    });
+  }
+
+  /**
+   * Exports the document in the specified format
+   *
+   * This method uses the Google Drive API to export the document
+   * in the requested format, returning it exactly as exported by the API.
+   *
+   * @param mimeType - MIME type for export (e.g., "text/html", "text/plain")
+   * @returns Promise<string> - Document content in the requested format
+   * @throws Error if export fails
+   */
+  async export(mimeType: string): Promise<string> {
+    // Get the Drive service from the Documents instance
+    const userEmail = this.docs.auth.subject!;
+    const gsuiteUser = this.docs.universe.gsuite.user(userEmail);
+    const drive = gsuiteUser.drive();
+
+    // Export via Drive API
+    const buffer = await drive.drive.files.export(
+      {
+        fileId: this.id,
+        mimeType,
+      },
+      { responseType: "arraybuffer" }
+    );
+
+    const content = Buffer.from(buffer.data as any).toString("utf-8");
+
+    // Return the content exactly as exported by the API
+    return content;
+  }
+
+  /**
+   * Exports the document as HTML
+   *
+   * This method uses the Google Drive API to export the document
+   * as HTML directly, returning it exactly as exported by the API.
+   *
+   * @returns Promise<string> - Document content as HTML
+   * @throws Error if export fails
+   */
+  async toHTML(): Promise<string> {
+    return this.export("text/html");
+  }
+
+  /**
+   * Exports the document as plain text
+   *
+   * This method uses the Google Drive API to export the document
+   * as plain text directly, returning it exactly as exported by the API.
+   *
+   * @returns Promise<string> - Document content as plain text
+   * @throws Error if export fails
+   */
+  async toPlainText(): Promise<string> {
+    return this.export("text/plain");
+  }
+
+  /**
+   * Exports the document as Markdown
+   *
+   * This method exports the document as HTML first, then converts it
+   * to Markdown using Turndown. This provides a clean Markdown representation
+   * of the document content.
+   *
+   * @returns Promise<string> - Document content as Markdown
+   * @throws Error if export or conversion fails
+   */
+  async toMarkdown(): Promise<string> {
+    const html = await this.toHTML();
+    const turndownService = new TurndownService();
+    turndownService.remove(["script", "style"]);
+    return turndownService.turndown(html).trim();
+  }
+}