@divizend/scratch-core 1.0.0

package/gsuite/documents/Documents.ts

@@ -0,0 +1,52 @@
+/**
+ * Documents - Google Docs Service Integration
+ *
+ * The Documents class provides access to Google Docs functionality
+ * through the Google Docs API v1. It serves as the entry point for
+ * all document operations within the system.
+ *
+ * Key Features:
+ * - Document opening and access
+ * - API client management and authentication
+ * - Integration with other Google Workspace services
+ * - Support for document editing and manipulation
+ *
+ * This class enables automated workflows that require document
+ * generation, template processing, and content manipulation.
+ *
+ * @class Documents
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { google, docs_v1 } from "googleapis";
+import { JWT } from "google-auth-library";
+import { Universe, Document } from "../..";
+
+export class Documents {
+  /** Google Docs API v1 client instance */
+  public readonly docs: docs_v1.Docs;
+
+  /**
+   * Creates a new Documents instance
+   *
+   * @param universe - Reference to the central Universe instance
+   * @param auth - JWT authentication for Docs access
+   */
+  constructor(public readonly universe: Universe, public readonly auth: JWT) {
+    this.docs = google.docs({ version: "v1", auth: this.auth });
+  }
+
+  /**
+   * Opens a document by ID for operations
+   *
+   * This method creates a Document instance that provides access
+   * to the document's content, structure, and editing capabilities.
+   *
+   * @param documentId - Google Docs document ID
+   * @returns Promise<Document> - Document instance for operations
+   */
+  async open(documentId: string): Promise<Document> {
+    return Document.construct(this, documentId);
+  }
+}

package/gsuite/documents/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Google Docs Module - Document Management and Operations
+ *
+ * This module provides comprehensive Google Docs integration including:
+ * - Documents: Main service for document operations
+ * - Document: Individual document management and editing
+ * - Content manipulation and placeholder replacement
+ * - Document formatting and styling
+ *
+ * The Documents module enables automated document generation,
+ * template processing, and content manipulation workflows.
+ *
+ * @module GoogleDocs
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export * from "./Documents";
+export * from "./Document";

package/gsuite/drive/Drive.ts

@@ -0,0 +1,118 @@
+/**
+ * Drive - Google Drive Service Integration
+ *
+ * The Drive class provides comprehensive access to Google Drive functionality
+ * including file operations, document copying, and file management. It serves
+ * as the primary interface for all Drive-related operations within the system.
+ *
+ * Key Features:
+ * - File opening and access
+ * - File copying and organization
+ * - Document template processing
+ * - Placeholder replacement and customization
+ * - Integration with other Google Workspace services
+ *
+ * This class enables automated workflows that require file manipulation,
+ * document generation, and template-based content creation.
+ *
+ * @class Drive
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { google, drive_v3 } from "googleapis";
+import { JWT } from "google-auth-library";
+import { Universe, DriveFile, DocumentPlaceholderReplacements } from "../..";
+
+/**
+ * Parameters for copying files in Google Drive
+ */
+export interface CopyFileParams {
+  /** ID of the source file to copy */
+  sourceFileId: string;
+  /** ID of the destination folder */
+  destFolderId: string;
+  /** Name for the new copied file */
+  name: string;
+}
+
+export class Drive {
+  /** Google Drive API v3 client instance */
+  public readonly drive: drive_v3.Drive;
+
+  /**
+   * Creates a new Drive instance
+   *
+   * @param universe - Reference to the central Universe instance
+   * @param auth - JWT authentication for Drive access
+   */
+  constructor(private readonly universe: Universe, private auth: JWT) {
+    this.drive = google.drive({ version: "v3", auth: this.auth });
+  }
+
+  /**
+   * Opens a file in Google Drive by ID
+   *
+   * This method creates a DriveFile instance that provides access
+   * to the file's content, metadata, and operations.
+   *
+   * @param fileId - Google Drive file ID
+   * @returns Promise<DriveFile> - File instance for operations
+   */
+  async open(fileId: string): Promise<DriveFile> {
+    return DriveFile.construct(this, fileId);
+  }
+
+  /**
+   * Copies a file to a new location in Google Drive
+   *
+   * This method creates a copy of the specified file in the destination
+   * folder with the new name. The original file remains unchanged.
+   *
+   * @param copyFileParams - Parameters for the copy operation
+   * @returns Promise<DriveFile> - Instance of the copied file
+   */
+  async copyFile({
+    sourceFileId,
+    destFolderId,
+    name,
+  }: CopyFileParams): Promise<DriveFile> {
+    const sourceFile = await this.open(sourceFileId);
+    return await sourceFile.copy(destFolderId, name);
+  }
+
+  /**
+   * Copies a document and optionally processes placeholder replacements
+   *
+   * This method combines file copying with document processing, making
+   * it ideal for template-based document generation workflows. It can
+   * automatically replace placeholders in the copied document.
+   *
+   * @param copyFileParams - Parameters for the copy operation
+   * @param replacements - Optional placeholder replacements for the document
+   * @returns Promise<DriveFile> - Instance of the processed copied file
+   */
+  async copyDocument(
+    copyFileParams: CopyFileParams,
+    replacements?: DocumentPlaceholderReplacements
+  ): Promise<DriveFile> {
+    const newFile = await this.copyFile(copyFileParams);
+    const newDocument = await newFile.asDocument();
+
+    if (replacements) {
+      await newDocument.replacePlaceholders(replacements);
+    }
+
+    return newFile;
+  }
+
+  /**
+   * Gets the GSuite user associated with this Drive instance
+   *
+   * This provides access to other Google Workspace services
+   * for the same authenticated user.
+   */
+  get user() {
+    return this.universe.gsuite.user(this.auth.subject!);
+  }
+}

package/gsuite/drive/DriveFile.ts

@@ -0,0 +1,147 @@
+/**
+ * DriveFile - Individual Google Drive File Operations
+ *
+ * The DriveFile class represents a single file in Google Drive and provides
+ * methods for file-specific operations including copying, conversion, and
+ * integration with other Google Workspace services.
+ *
+ * Key Features:
+ * - File metadata access and manipulation
+ * - File copying and organization
+ * - PDF export and conversion
+ * - Document integration and processing
+ * - Cross-service file operations
+ *
+ * This class serves as the primary interface for working with individual
+ * files in Google Drive, enabling complex file workflows and automation.
+ *
+ * @class DriveFile
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { drive_v3 } from "googleapis";
+import { Drive, Document } from "../..";
+
+export class DriveFile {
+  /**
+   * Creates a new DriveFile instance
+   *
+   * @param drive - Reference to the Drive service instance
+   * @param file - Raw Google Drive API file data
+   */
+  constructor(
+    private readonly drive: Drive,
+    public readonly file: drive_v3.Schema$File
+  ) {}
+
+  /**
+   * Constructs a DriveFile instance from a file ID
+   *
+   * This factory method fetches the file metadata from Google Drive
+   * and creates a DriveFile instance ready for operations.
+   *
+   * @param drive - Drive service instance
+   * @param fileId - Google Drive file ID
+   * @returns Promise<DriveFile> - Initialized file instance
+   */
+  static async construct(drive: Drive, fileId: string) {
+    const file = await drive.drive.files.get({
+      fileId,
+      supportsAllDrives: true,
+    });
+    return new DriveFile(drive, file.data);
+  }
+
+  /**
+   * Gets the unique identifier for this file
+   *
+   * The file ID is used for all Google Drive API operations
+   * and can be used to reference this file in other services.
+   */
+  get id(): string {
+    return this.file.id!;
+  }
+
+  /**
+   * Copies this file to a new location in Google Drive
+   *
+   * This method creates a copy of the current file in the specified
+   * destination folder with the new name. The original file remains
+   * unchanged and accessible.
+   *
+   * @param destFolderId - ID of the destination folder
+   * @param name - Name for the copied file
+   * @returns Promise<DriveFile> - Instance of the copied file
+   */
+  async copy(destFolderId: string, name: string) {
+    return DriveFile.construct(
+      this.drive,
+      (
+        await this.drive.drive.files.copy({
+          fileId: this.id,
+          supportsAllDrives: true,
+          requestBody: { name, parents: [destFolderId] },
+        })
+      ).data.id!
+    );
+  }
+
+  /**
+   * Opens this file as a Google Document for editing
+   *
+   * This method provides access to the document editing capabilities
+   * of Google Docs, enabling content manipulation and placeholder
+   * replacement operations.
+   *
+   * @returns Promise<Document> - Document instance for editing
+   */
+  async asDocument(): Promise<Document> {
+    return this.drive.user.documents().open(this.id);
+  }
+
+  /**
+   * Exports this file as a PDF document
+   *
+   * This method converts the file to PDF format and returns the
+   * content as a Buffer. Useful for creating downloadable versions
+   * or email attachments.
+   *
+   * @returns Promise<Buffer> - PDF content as a buffer
+   */
+  async pdf(): Promise<Buffer> {
+    return Buffer.from(
+      (
+        await this.drive.drive.files.export(
+          {
+            fileId: this.id,
+            mimeType: "application/pdf",
+          },
+          { responseType: "arraybuffer" }
+        )
+      ).data as any
+    );
+  }
+
+  async download(): Promise<Buffer> {
+    const file = (
+      await this.drive.drive.files.get(
+        {
+          fileId: this.id,
+          alt: "media",
+        },
+        { responseType: "stream" }
+      )
+    ).data;
+    const chunks: Buffer[] = [];
+    for await (const chunk of file) {
+      chunks.push(chunk);
+    }
+    return Buffer.concat(chunks);
+  }
+
+  async text(): Promise<string> {
+    const download = await this.download();
+    return download.toString("utf8");
+  }
+}

package/gsuite/drive/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Google Drive Module - File Management and Operations
+ *
+ * This module provides comprehensive Google Drive integration including:
+ * - Drive: Main Drive service and file operations
+ * - DriveFile: Individual file management and manipulation
+ * - File copying, moving, and organization
+ * - Folder management and file sharing
+ *
+ * The Drive module enables seamless file operations within Google Workspace,
+ * supporting automated workflows that require file management capabilities.
+ *
+ * @module GoogleDrive
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export * from "./Drive";
+export * from "./DriveFile";