@divizend/scratch-core 1.0.0

package/gsuite/gmail/GmailMessagePart.ts

@@ -0,0 +1,298 @@
+/**
+ * GmailMessagePart - Email Part and Attachment Management
+ *
+ * The GmailMessagePart class represents individual parts of an email message,
+ * including body text, HTML content, and file attachments. It implements the
+ * Fragment interface to provide consistent access to different content types.
+ *
+ * Key Features:
+ * - MIME part handling and content extraction
+ * - Attachment management and downloading
+ * - Content encoding and charset handling
+ * - Header parsing and metadata access
+ * - Multiple serving modes for different use cases
+ *
+ * This class handles the complex MIME structure of emails and provides
+ * a unified interface for accessing various content types within messages.
+ *
+ * @class GmailMessagePart
+ * @implements Fragment
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { gmail_v1 } from "googleapis";
+import {
+  Gmail,
+  GmailMessage,
+  Fragment,
+  FragmentServingMode,
+  GmailMessagePartURI,
+  URI,
+  Universe,
+} from "../..";
+import { qpDecode } from "./utils";
+
+/**
+ * Extended message part data with additional properties
+ *
+ * Extends the Gmail API message part with convenience properties
+ * for headers and body content management.
+ */
+export type GmailMessagePartData = gmail_v1.Schema$MessagePart & {
+  /** Map of lowercase header names to values for easy access */
+  headersMap?: { [key: string]: string };
+  /** Extended body data with optional buffer for content */
+  body?: gmail_v1.Schema$MessagePartBody & {
+    buffer?: Buffer;
+  };
+};
+
+export class GmailMessagePart implements Fragment {
+  /**
+   * Creates a new GmailMessagePart instance
+   *
+   * The constructor automatically processes headers into a map for
+   * efficient lookup and initializes the part with the provided data.
+   *
+   * @param gmail - Reference to the Gmail service instance
+   * @param part - Raw message part data from Gmail API
+   * @param messageId - ID of the parent message
+   * @param isFull - Whether the part contains full content
+   */
+  constructor(
+    private readonly gmail: Gmail,
+    public readonly part: GmailMessagePartData,
+    public readonly messageId: string,
+    public readonly isFull: boolean
+  ) {
+    // Create a map of lowercase header names to values for efficient lookup
+    const headersMap: { [key: string]: string } = {};
+    for (const header of this.part.headers || []) {
+      headersMap[header.name!.toLowerCase()] = header.value!;
+    }
+    this.part.headersMap = headersMap;
+  }
+
+  /**
+   * Creates a GmailMessagePart from a URI
+   *
+   * This factory method parses the URI to extract the email address,
+   * message ID, and part ID, then creates the appropriate instances
+   * to fetch the message part.
+   *
+   * @param universe - Reference to the central Universe instance
+   * @param uri - URI identifying the message part to retrieve
+   * @returns Promise<GmailMessagePart> - The requested message part
+   */
+  static async fromURI(
+    universe: Universe,
+    uri: URI
+  ): Promise<GmailMessagePart> {
+    const gmailMessagePartUri = GmailMessagePartURI.fromURI(uri);
+    const gmail = universe.gsuite.user(gmailMessagePartUri.email).gmail();
+    return GmailMessagePart.fromMessageIdAndPartId(
+      gmail,
+      gmailMessagePartUri.messageId,
+      gmailMessagePartUri.partId
+    );
+  }
+
+  /**
+   * Creates a GmailMessagePart from message ID and part ID
+   *
+   * This factory method fetches the full message first, then
+   * locates the specific part within the message structure.
+   *
+   * @param gmail - Gmail service instance for the user
+   * @param messageId - Gmail message identifier
+   * @param partId - Gmail message part identifier
+   * @returns Promise<GmailMessagePart> - The requested message part
+   */
+  static async fromMessageIdAndPartId(
+    gmail: Gmail,
+    messageId: string,
+    partId: string
+  ): Promise<GmailMessagePart> {
+    const message = await GmailMessage.fromMessageId(gmail, messageId);
+    return GmailMessagePart.fromMessageAndPartId(gmail, message, partId);
+  }
+
+  /**
+   * Creates a GmailMessagePart from an existing message and part ID
+   *
+   * This factory method searches through the message's MIME structure
+   * to find the part with the specified ID, handling nested multipart
+   * messages recursively.
+   *
+   * @param gmail - Gmail service instance for the user
+   * @param message - Gmail message containing the part
+   * @param partId - Gmail message part identifier
+   * @returns Promise<GmailMessagePart> - The requested message part
+   * @throws Error if the part is not found in the message
+   */
+  static async fromMessageAndPartId(
+    gmail: Gmail,
+    message: GmailMessage,
+    partId: string
+  ): Promise<GmailMessagePart> {
+    // Recursive function to find a part by ID in the MIME structure
+    const findPart = (part: any) => {
+      if (part.partId === partId) {
+        return part;
+      }
+      if (Array.isArray(part.parts)) {
+        for (const subPart of part.parts) {
+          const body: any = findPart(subPart);
+          if (body) {
+            return body;
+          }
+        }
+      }
+      return null;
+    };
+
+    const part = findPart(message.data.payload);
+    if (!part) {
+      throw new Error(`Part not found: ${partId}`);
+    }
+
+    return GmailMessagePart.fromMessageAndPart(gmail, message, part);
+  }
+
+  /**
+   * Creates a GmailMessagePart from an existing message and part data
+   *
+   * This factory method creates a prototype part and then fetches
+   * the full content if needed.
+   *
+   * @param gmail - Gmail service instance for the user
+   * @param message - Gmail message containing the part
+   * @param part - Raw part data from the message
+   * @returns Promise<GmailMessagePart> - The full message part
+   */
+  static async fromMessageAndPart(
+    gmail: Gmail,
+    message: GmailMessage,
+    part: GmailMessagePartData
+  ): Promise<GmailMessagePart> {
+    const proto = new GmailMessagePart(gmail, part, message.message.id!, false);
+    return proto.fetch();
+  }
+
+  /**
+   * Fetches the full content of the message part
+   *
+   * This method retrieves the complete part content including
+   * body data and attachments. It handles different content
+   * encoding methods and attachment downloading.
+   *
+   * @returns Promise<GmailMessagePart> - Part with full content
+   */
+  async fetch(): Promise<GmailMessagePart> {
+    if (this.isFull) {
+      return this;
+    }
+
+    let buffer: Buffer | undefined = undefined;
+    if (this.part.body?.data) {
+      // Decode base64-encoded content
+      buffer = Buffer.from(this.part.body.data, "base64");
+    } else if (this.part.body?.attachmentId) {
+      // Download attachment if it's an attachment
+      buffer = Buffer.from(
+        (
+          await this.gmail.gmail.users.messages.attachments.get({
+            userId: "me",
+            messageId: this.messageId,
+            id: this.part.body.attachmentId,
+          })
+        ).data.data!,
+        "base64"
+      );
+    } else {
+      // If no data and no attachment, return an empty buffer
+      buffer = Buffer.alloc(0);
+    }
+
+    return new GmailMessagePart(
+      this.gmail,
+      {
+        ...this.part,
+        body: {
+          ...this.part.body,
+          buffer: buffer!,
+        },
+      },
+      this.messageId,
+      true
+    );
+  }
+
+  get uri() {
+    return `gmail://${this.gmail.email}/message/${this.messageId}/part/${this.part.partId}`;
+  }
+
+  async serve(format: FragmentServingMode): Promise<{
+    headers: { name: string; value: string }[];
+    data: Buffer;
+  }> {
+    if (!this.isFull) {
+      throw new Error("Part is not full");
+    }
+
+    if (format === FragmentServingMode.ORIGINAL) {
+      return {
+        headers: this.part.headers!.map((header) => ({
+          name: header.name!,
+          value: header.value!,
+        })),
+        data: this.part.body?.buffer || Buffer.alloc(0),
+      };
+    } else if (format === FragmentServingMode.JSON) {
+      return {
+        headers: [{ name: "Content-Type", value: "application/json" }],
+        data: Buffer.from(JSON.stringify(this.part)),
+      };
+    } else {
+      throw new Error(`Unknown serving mode: ${format}`);
+    }
+  }
+
+  getHeader(name: string): string | undefined {
+    return this.part.headersMap?.[name.toLowerCase()];
+  }
+
+  getCharset(): BufferEncoding {
+    const ct = this.getHeader("content-type") || "";
+    const m = /charset\s*=\s*"?([^";]+)"?/i.exec(ct);
+    const cs = (m?.[1] || "utf-8").toLowerCase();
+    if (/(utf-8|utf8)/i.test(cs)) return "utf8";
+    if (/(iso-8859-1|latin1)/i.test(cs)) return "latin1";
+    // default to utf-8
+    return "utf8";
+  }
+
+  async asText(): Promise<string> {
+    if (!this.isFull) {
+      throw new Error("Part is not full");
+    }
+
+    // decode transfer-encoding if necessary (ignore base64, it's already decoded)
+    let raw = this.part.body?.buffer!;
+    const cte = (
+      this.getHeader("content-transfer-encoding") || ""
+    ).toLowerCase();
+    if (cte === "quoted-printable") {
+      raw = qpDecode(raw);
+    }
+
+    // always decode with utf8 first (because some emails wrongly say that they are iso-8859-1, but they are actually utf8)
+    const enc = this.getCharset();
+    const ret = raw.toString("utf8");
+    if (Buffer.from(ret, "utf8").equals(raw)) {
+      return ret; // valid utf8
+    }
+    return raw.toString(enc);
+  }
+}

package/gsuite/gmail/GmailThread.ts

@@ -0,0 +1,97 @@
+/**
+ * GmailThread - Email Conversation Management
+ *
+ * The GmailThread class represents a conversation thread in Gmail, which
+ * groups related email messages together. Threads provide a way to view
+ * the complete conversation history in a single, organized view.
+ *
+ * Key Features:
+ * - Thread metadata and conversation overview
+ * - Access to all messages within the thread
+ * - Thread subject and snippet extraction
+ *
+ * This class simplifies working with email conversations by providing
+ * a high-level interface to thread properties and message collections.
+ *
+ * @class GmailThread
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { gmail_v1 } from "googleapis";
+import { Gmail, GmailMessage } from "../..";
+
+export class GmailThread {
+  /**
+   * Creates a new GmailThread instance
+   *
+   * @param gmail - Reference to the Gmail service instance
+   * @param thread - Raw Gmail API thread data
+   */
+  constructor(
+    private readonly gmail: Gmail,
+    public readonly thread: gmail_v1.Schema$Thread,
+    public readonly messages: GmailMessage[]
+  ) {}
+
+  async fetch(): Promise<GmailThread> {
+    if (this.messages.length > 0) {
+      return this;
+    }
+
+    const threadFull = await this.gmail.gmail.users.threads.get({
+      userId: "me",
+      id: this.id!,
+    });
+
+    if (!threadFull.data.messages) {
+      throw new Error("Thread has no messages: " + this.id);
+    }
+
+    const messages = threadFull.data.messages?.map((message) => {
+      return new GmailMessage(this.gmail, message, true);
+    });
+
+    return new GmailThread(this.gmail, threadFull.data, messages);
+  }
+
+  get id() {
+    return this.thread.id!;
+  }
+
+  /**
+   * Gets the conversation snippet/preview
+   *
+   * The snippet provides a brief preview of the conversation,
+   * typically showing the most recent message content or subject.
+   */
+  get snippet() {
+    return this.thread.snippet;
+  }
+
+  /**
+   * Gets the history ID for change tracking
+   *
+   * The history ID is used by Gmail to track changes to the thread
+   * and enable efficient synchronization of updates.
+   */
+  get historyId() {
+    return this.thread.historyId;
+  }
+
+  /**
+   * Gets the subject from the first message in the thread
+   *
+   * This provides the original conversation subject, which typically
+   * remains consistent throughout the thread's lifecycle.
+   *
+   * @returns The thread subject, or undefined if no messages exist
+   */
+  get subject(): string | undefined {
+    if (this.messages.length === 0) {
+      return "No messages";
+    }
+
+    return this.messages[0]!.subject;
+  }
+}

package/gsuite/gmail/index.ts

@@ -0,0 +1,5 @@
+export * from "./Gmail";
+export * from "./GmailLabel";
+export * from "./GmailMessage";
+export * from "./GmailMessagePart";
+export * from "./GmailThread";

package/gsuite/gmail/utils.ts

@@ -0,0 +1,184 @@
+/**
+ * Gmail Utility Functions
+ *
+ * This module provides utility functions for Gmail operations including:
+ * - Content encoding and decoding (quoted-printable, base64)
+ * - HTML processing and sanitization
+ * - URL rewriting for embedded content
+ * - MIME message formatting and composition
+ *
+ * These utilities handle the low-level details of email processing,
+ * content transformation, and message composition that are common
+ * across different Gmail operations.
+ *
+ * @module GmailUtils
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+/**
+ * Decodes quoted-printable encoded content
+ *
+ * Quoted-printable is a content transfer encoding used in email
+ * that represents 8-bit data using only 7-bit printable ASCII characters.
+ * This function handles both soft line breaks and hex-encoded bytes.
+ *
+ * @param buf - Buffer containing quoted-printable encoded data
+ * @returns Buffer with decoded content
+ */
+export function qpDecode(buf: Buffer): Buffer {
+  // Convert to string for ease; handle soft line breaks and =XX hex
+  let s = buf.toString("utf8");
+  // remove soft line breaks
+  s = s.replace(/=\r?\n/g, "");
+  // replace =HH hex bytes
+  s = s.replace(/=([A-Fa-f0-9]{2})/g, (_, hex) =>
+    String.fromCharCode(parseInt(hex, 16))
+  );
+  return Buffer.from(s, "utf8");
+}
+
+/**
+ * Escapes special regex characters in a string
+ *
+ * This function escapes characters that have special meaning in regular
+ * expressions, allowing the string to be used safely in regex patterns.
+ *
+ * @param s - String to escape
+ * @returns String with regex special characters escaped
+ */
+export function escapeRegExp(s: string) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+/**
+ * Rewrites CID URLs in HTML/CSS to fragment URIs
+ *
+ * Content-ID (CID) URLs are used in multipart emails to reference
+ * embedded content like images. This function converts them to
+ * fragment URIs that can be served by the system.
+ *
+ * @param html - HTML content containing CID URLs
+ * @param uri - Base URI for the message
+ * @param cidToPart - Mapping of CID values to part IDs
+ * @returns HTML with CID URLs rewritten to fragment URIs
+ */
+export function rewriteCidUrls(
+  html: string,
+  uri: string,
+  cidToPart: { [key: string]: string }
+): string {
+  // To avoid partial overlaps, replace longest CIDs first
+  const keys = Object.keys(cidToPart).sort((a, b) => b.length - a.length);
+  for (const cid of keys) {
+    const partId = cidToPart[cid];
+    const url = `/fragment?uri=${encodeURIComponent(uri + "/part/" + partId)}`;
+    const pat = new RegExp(
+      `cid:(?:%3C|<)?${escapeRegExp(cid)}(?:%3E|>)?`,
+      "gi"
+    );
+    html = html.replace(pat, url);
+  }
+  return html;
+}
+
+/**
+ * Converts a buffer or string to base64url encoding
+ *
+ * Base64url is a URL-safe variant of base64 encoding that replaces
+ * '+' with '-' and '/' with '_', and removes padding characters.
+ * This is commonly used in JWT tokens and other web-safe encodings.
+ *
+ * @param buf - Buffer or string to encode
+ * @returns Base64url encoded string
+ */
+export function base64Url(buf: Buffer | string) {
+  return (typeof buf === "string" ? Buffer.from(buf, "utf8") : buf)
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/g, "");
+}
+
+/**
+ * Chunks a string into 76-character lines
+ *
+ * This function breaks long strings into lines of 76 characters
+ * or less, which is the standard line length for MIME messages.
+ * Each line is terminated with CRLF (\r\n).
+ *
+ * @param s - String to chunk
+ * @returns String with line breaks every 76 characters
+ */
+export function chunk76(s: string) {
+  return s.replace(/.{1,76}/g, "$&\r\n");
+}
+
+/**
+ * Escapes HTML special characters
+ *
+ * Converts HTML special characters to their entity equivalents
+ * to prevent HTML injection and ensure safe content display.
+ *
+ * @param s - String containing HTML content
+ * @returns String with HTML special characters escaped
+ */
+export function escapeHtml(s: string) {
+  return s.replace(
+    /[&<>"']/g,
+    (c) =>
+      ({
+        "&": "&amp;",
+        "<": "&lt;",
+        ">": "&gt;",
+        '"': "&quot;",
+        "'": "&#39;",
+      }[c]!)
+  );
+}
+
+/**
+ * Converts plain text to HTML with line breaks
+ *
+ * This function wraps plain text in HTML div tags and converts
+ * line breaks to HTML br tags for proper display in web browsers.
+ *
+ * @param s - Plain text string
+ * @returns HTML string with line breaks converted to br tags
+ */
+export function htmlFromText(s: string) {
+  return `<div>${escapeHtml(s).replace(/\r?\n/g, "<br>")}</div>`;
+}
+
+/**
+ * Strips HTML tags to extract plain text
+ *
+ * Removes all HTML tags and converts common HTML elements like
+ * br and p tags to appropriate line breaks for plain text output.
+ *
+ * @param html - HTML string to convert
+ * @returns Plain text with HTML tags removed
+ */
+export function stripHtmlToText(html: string) {
+  return html
+    .replace(/<br\s*\/?>/gi, "\n")
+    .replace(/<\/p>/gi, "\n\n")
+    .replace(/<[^>]+>/g, "")
+    .trim();
+}
+
+/**
+ * Encodes display names for email headers
+ *
+ * This function handles display names in email headers, particularly
+ * for international characters. It uses base64 encoding for non-ASCII
+ * names and proper quoting for ASCII names.
+ *
+ * @param name - Display name to encode
+ * @returns Properly encoded display name for email headers
+ */
+export function encodeDisplayName(name: string) {
+  return /[^\x00-\x7F]/.test(name)
+    ? `=?UTF-8?B?${Buffer.from(name, "utf8").toString("base64")}?=`
+    : `"${name.replace(/"/g, '\\"')}"`;
+}

package/gsuite/index.ts

@@ -0,0 +1,28 @@
+/**
+ * GSuite Module - Google Workspace Integration
+ *
+ * This module provides comprehensive integration with Google Workspace services
+ * including Gmail, Google Drive, Google Sheets, Google Docs, and administrative
+ * functions.
+ *
+ * The module is organized into specialized submodules:
+ * - core: Organization management and user authentication
+ * - gmail: Email processing and management
+ * - drive: File storage and management
+ * - spreadsheets: Data analysis and spreadsheet operations
+ * - documents: Document creation and processing
+ *
+ * All services support multi-organization deployments with proper isolation
+ * and enterprise-grade security through service account authentication.
+ *
+ * @module GSuite
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export * from "./core";
+export * from "./documents";
+export * from "./drive";
+export * from "./gmail";
+export * from "./spreadsheets";
+export * from "./utils";

package/gsuite/spreadsheets/CellValue.ts

@@ -0,0 +1,71 @@
+import { sheets_v4 } from "googleapis";
+import { jsDateToSheetsSerial } from "./utils";
+
+export enum CellFormat {
+  Date_de = "Date_de",
+  Currency_EUR_de = "Currency_EUR_de",
+  RightAligned = "RightAligned",
+}
+
+const CellFormats: { [key in CellFormat]: sheets_v4.Schema$CellFormat } = {
+  [CellFormat.Date_de]: {
+    numberFormat: {
+      type: "DATE",
+      pattern: "dd.mm.yyyy",
+    },
+  },
+  [CellFormat.Currency_EUR_de]: {
+    numberFormat: {
+      type: "CURRENCY",
+      pattern: "#,##0.00 €",
+    },
+  },
+  [CellFormat.RightAligned]: {
+    horizontalAlignment: "RIGHT",
+  },
+};
+
+function isDateCellFormat(
+  format: CellFormat | CellFormat[] | undefined
+): boolean {
+  if (Array.isArray(format)) {
+    return format.some((f) => isDateCellFormat(f));
+  }
+  return format === CellFormat.Date_de;
+}
+
+export type CellValue =
+  | string
+  | number
+  | { value: any; format?: CellFormat | CellFormat[] };
+
+export function transformCellValueForSheets(
+  value: CellValue
+): sheets_v4.Schema$CellData {
+  const newCell: sheets_v4.Schema$CellData = {};
+  if (typeof value === "string") {
+    newCell.userEnteredValue = { stringValue: value };
+  } else if (typeof value === "number") {
+    newCell.userEnteredValue = { numberValue: value };
+  } else if (typeof value === "object") {
+    if (isDateCellFormat(value.format)) {
+      newCell.userEnteredValue = {
+        numberValue: jsDateToSheetsSerial(value.value),
+      };
+    } else if (typeof value.value === "string") {
+      newCell.userEnteredValue = { stringValue: value.value };
+    } else if (typeof value.value === "number") {
+      newCell.userEnteredValue = { numberValue: value.value };
+    }
+
+    if (Array.isArray(value.format)) {
+      newCell.userEnteredFormat = Object.assign(
+        {},
+        ...value.format.map((f) => CellFormats[f])
+      );
+    } else if (value.format) {
+      newCell.userEnteredFormat = CellFormats[value.format];
+    }
+  }
+  return newCell;
+}