@divizend/scratch-core 1.0.0

package/gsuite/spreadsheets/Sheet.ts

@@ -0,0 +1,128 @@
+/**
+ * Sheet - Individual Sheet Operations and Data Management
+ *
+ * The Sheet class represents a single sheet within a Google Sheets
+ * spreadsheet and provides methods for data access, manipulation,
+ * and operations on sheet content.
+ *
+ * Key Features:
+ * - Sheet metadata and properties access
+ * - Range-based data retrieval
+ * - Column-specific operations
+ * - Row appending and data insertion
+ * - Integration with Google Sheets API
+ *
+ * This class enables fine-grained control over individual sheets,
+ * supporting complex data operations and workflow automation.
+ *
+ * @class Sheet
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { sheets_v4 } from "googleapis";
+import {
+  Spreadsheet,
+  CellValue,
+  transformCellValueForSheets,
+  SheetValues,
+} from "../..";
+
+export class Sheet {
+  /**
+   * Creates a new Sheet instance
+   *
+   * @param spreadsheet - Reference to the parent Spreadsheet instance
+   * @param sheet - Raw Google Sheets API sheet data
+   */
+  constructor(
+    private readonly spreadsheet: Spreadsheet,
+    public readonly sheet: sheets_v4.Schema$Sheet
+  ) {}
+
+  /**
+   * Gets the display name of the sheet
+   *
+   * This is the name that appears on the sheet tab in Google Sheets
+   * and is used for range references and sheet identification.
+   */
+  get name() {
+    return this.sheet.properties!.title!;
+  }
+
+  /**
+   * Gets the unique identifier for the sheet
+   *
+   * The sheet ID is used internally by Google Sheets for API operations
+   * and should not be displayed to users.
+   */
+  get id() {
+    return this.sheet.properties!.sheetId!;
+  }
+
+  /**
+   * Retrieves values from a specified range in the sheet
+   *
+   * This method fetches data from the Google Sheets API for the
+   * specified range and returns it as a SheetValues instance for
+   * further processing and manipulation.
+   *
+   * @param range - A1 notation range (e.g., "A1:B10", "C:C")
+   * @returns Promise<SheetValues> - Values from the specified range
+   * @throws Error if no values are found for the range
+   */
+  async getValues(range: string) {
+    const values = (
+      await this.spreadsheet.spreadsheets.sheets.spreadsheets.values.get({
+        spreadsheetId: this.spreadsheet.id,
+        range: `${this.name}!${range}`,
+      })
+    ).data.values;
+
+    if (!values) {
+      throw new Error(`No values found for range ${range}`);
+    }
+
+    return new SheetValues(this, values);
+  }
+
+  /**
+   * Retrieves all values from a specific column
+   *
+   * This method provides convenient access to column data by
+   * specifying just the column letter (e.g., "A", "B", "C").
+   *
+   * @param column - Column letter to retrieve
+   * @returns Promise<SheetValues> - All values from the specified column
+   */
+  async getColumn(column: string) {
+    return this.getValues(`${column}:${column}`);
+  }
+
+  /**
+   * Appends a new row of data to the sheet
+   *
+   * This method adds a new row at the bottom of the sheet with
+   * the specified values. The values are automatically formatted
+   * according to their CellValue specifications.
+   *
+   * @param values - Array of CellValue objects to append
+   * @throws Error if the append operation fails
+   */
+  async appendRow(values: CellValue[]) {
+    await this.spreadsheet.spreadsheets.sheets.spreadsheets.batchUpdate({
+      spreadsheetId: this.spreadsheet.id,
+      requestBody: {
+        requests: [
+          {
+            appendCells: {
+              sheetId: this.id,
+              rows: [{ values: values.map(transformCellValueForSheets) }],
+              fields: "*",
+            },
+          },
+        ],
+      },
+    });
+  }
+}

package/gsuite/spreadsheets/SheetValues.ts

@@ -0,0 +1,12 @@
+import { Sheet } from "../..";
+
+export class SheetValues {
+  constructor(
+    private readonly sheet: Sheet,
+    private readonly values: any[][]
+  ) {}
+
+  last() {
+    return this.values.slice(-1)[0]![0];
+  }
+}

package/gsuite/spreadsheets/Spreadsheet.ts

@@ -0,0 +1,76 @@
+/**
+ * Spreadsheet - Individual Spreadsheet Management
+ *
+ * The Spreadsheet class represents a single Google Sheets spreadsheet
+ * and provides access to its individual sheets and operations. It serves
+ * as the primary interface for working with spreadsheet content.
+ *
+ * Key Features:
+ * - Sheet access and management
+ * - Spreadsheet metadata and properties
+ * - Sheet-by-name lookup and access
+ * - Integration with Google Sheets API
+ *
+ * This class enables operations on individual spreadsheets, providing
+ * access to their sheets and data for processing and manipulation.
+ *
+ * @class Spreadsheet
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { sheets_v4 } from "googleapis";
+import { Sheet, Spreadsheets } from "../..";
+
+export class Spreadsheet {
+  /** Array of Sheet instances for all sheets in the spreadsheet */
+  public readonly sheets: Sheet[];
+
+  /**
+   * Creates a new Spreadsheet instance
+   *
+   * @param spreadsheets - Reference to the Spreadsheets service
+   * @param id - Google Sheets spreadsheet ID
+   * @param sheetsRaw - Raw sheet data from the API
+   */
+  constructor(
+    public readonly spreadsheets: Spreadsheets,
+    public readonly id: string,
+    sheetsRaw: sheets_v4.Schema$Sheet[]
+  ) {
+    // Create Sheet instances for all sheets in the spreadsheet
+    this.sheets = sheetsRaw.map((s) => new Sheet(this, s));
+  }
+
+  /**
+   * Constructs a Spreadsheet instance from a spreadsheet ID
+   *
+   * This factory method fetches the spreadsheet metadata and creates
+   * Sheet instances for all sheets within the spreadsheet.
+   *
+   * @param spreadsheets - Spreadsheets service instance
+   * @param spreadsheetId - Google Sheets spreadsheet ID
+   * @returns Promise<Spreadsheet> - Initialized spreadsheet instance
+   */
+  static async construct(spreadsheets: Spreadsheets, spreadsheetId: string) {
+    const sheetsRaw = await spreadsheets.sheets.spreadsheets.get({
+      spreadsheetId,
+      fields: "sheets.properties",
+    });
+    return new Spreadsheet(spreadsheets, spreadsheetId, sheetsRaw.data.sheets!);
+  }
+
+  /**
+   * Gets a sheet by name from the spreadsheet
+   *
+   * This method provides convenient access to individual sheets
+   * within the spreadsheet for data operations and manipulation.
+   *
+   * @param name - Name of the sheet to retrieve
+   * @returns Promise<Sheet> - Sheet instance for the specified name
+   * @throws Error if the sheet is not found
+   */
+  async getSheet(name: string): Promise<Sheet> {
+    return this.sheets.find((s) => s.name === name)!;
+  }
+}

package/gsuite/spreadsheets/Spreadsheets.ts

@@ -0,0 +1,52 @@
+/**
+ * Spreadsheets - Google Sheets Service Integration
+ *
+ * The Spreadsheets class provides access to Google Sheets functionality
+ * through the Google Sheets API v4. It serves as the entry point for
+ * all spreadsheet operations within the system.
+ *
+ * Key Features:
+ * - Spreadsheet opening and access
+ * - API client management and authentication
+ * - Integration with other Google Workspace services
+ * - Support for complex spreadsheet operations
+ *
+ * This class enables automated workflows that require spreadsheet
+ * data processing, financial calculations, and data organization.
+ *
+ * @class Spreadsheets
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+import { google, sheets_v4 } from "googleapis";
+import { JWT } from "google-auth-library";
+import { Universe, Spreadsheet } from "../..";
+
+export class Spreadsheets {
+  /** Google Sheets API v4 client instance */
+  public readonly sheets: sheets_v4.Sheets;
+
+  /**
+   * Creates a new Spreadsheets instance
+   *
+   * @param universe - Reference to the central Universe instance
+   * @param auth - JWT authentication for Sheets access
+   */
+  constructor(private readonly universe: Universe, private auth: JWT) {
+    this.sheets = google.sheets({ version: "v4", auth: this.auth });
+  }
+
+  /**
+   * Opens a spreadsheet by ID for operations
+   *
+   * This method creates a Spreadsheet instance that provides access
+   * to the spreadsheet's sheets, data, and operations.
+   *
+   * @param spreadsheetId - Google Sheets spreadsheet ID
+   * @returns Promise<Spreadsheet> - Spreadsheet instance for operations
+   */
+  async open(spreadsheetId: string): Promise<Spreadsheet> {
+    return Spreadsheet.construct(this, spreadsheetId);
+  }
+}

package/gsuite/spreadsheets/index.ts

@@ -0,0 +1,25 @@
+/**
+ * Google Sheets Module - Spreadsheet Management and Operations
+ *
+ * This module provides comprehensive Google Sheets integration including:
+ * - Spreadsheets: Main service for spreadsheet operations
+ * - Spreadsheet: Individual spreadsheet management
+ * - Sheet: Individual sheet operations and data access
+ * - CellValue: Cell data handling and formatting
+ * - SheetValues: Bulk data operations and column management
+ * - Utilities: Helper functions for common operations
+ *
+ * The Spreadsheets module enables automated data processing, financial
+ * record keeping, and complex spreadsheet operations within workflows.
+ *
+ * @module GoogleSheets
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export * from "./Spreadsheets";
+export * from "./Spreadsheet";
+export * from "./Sheet";
+export * from "./CellValue";
+export * from "./SheetValues";
+export * from "./utils";

package/gsuite/spreadsheets/utils.ts

@@ -0,0 +1,52 @@
+// Google Sheets date serials:
+// Day 0 = 1899-12-30 (UTC). Fractional part = time-of-day.
+const SHEETS_EPOCH_UTC_MS = Date.UTC(1899, 11, 30);
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+export type YMD = readonly [year: number, month: number, day: number];
+
+/** Returns the Google Sheets serial for a calendar DATE (no time). */
+export function jsDateToSheetsSerial(input: Date | string | YMD): number {
+  let y: number, m: number, d: number;
+
+  if (input instanceof Date) {
+    // Use UTC parts so local timezone/DST can't shift the day.
+    y = input.getUTCFullYear();
+    m = input.getUTCMonth() + 1;
+    d = input.getUTCDate();
+  } else if (Array.isArray(input)) {
+    [y, m, d] = input;
+  } else if (typeof input === "string") {
+    // Accepts "YYYY_MM_DD" or "YYYY-MM-DD"
+    const m1 = /^(\d{4})[-_](\d{2})[-_](\d{2})$/.exec(input);
+    if (!m1) {
+      throw new RangeError(
+        `Unrecognized date string: "${input}". Use "YYYY-MM-DD".`
+      );
+    }
+    y = Number(m1[1]);
+    m = Number(m1[2]);
+    d = Number(m1[3]);
+  } else {
+    // Should be unreachable due to the signature, but keeps TS happy in looser configs.
+    throw new TypeError("Unsupported input for jsDateToSheetsSerial()");
+  }
+
+  // Build UTC midnight of the intended calendar date.
+  const utcMidnightMs = Date.UTC(y, m - 1, d);
+
+  // Validate (catches impossible dates like 1900-02-29).
+  const check = new Date(utcMidnightMs);
+  if (
+    check.getUTCFullYear() !== y ||
+    check.getUTCMonth() !== m - 1 ||
+    check.getUTCDate() !== d
+  ) {
+    const pad = (n: number) => String(n).padStart(2, "0");
+    throw new RangeError(`Invalid calendar date: ${y}-${pad(m)}-${pad(d)}`);
+  }
+
+  // Exact day count since 1899-12-30. Round to kill any FP dust.
+  const serial = (utcMidnightMs - SHEETS_EPOCH_UTC_MS) / MS_PER_DAY;
+  return Math.round(serial);
+}

package/gsuite/utils.ts

@@ -0,0 +1,104 @@
+/**
+ * GSuite Utilities - Helper Functions
+ *
+ * Provides utility functions for Google Workspace operations.
+ *
+ * @module GSuiteUtils
+ * @version 1.0.0
+ */
+
+import { GSuiteUser, Document, Spreadsheet, Sheet, Spreadsheets } from "..";
+
+/**
+ * Extracts a Google Drive/Docs file ID from a URL or returns the input if it's already a file ID
+ *
+ * Supports various Google Drive/Docs URL formats:
+ * - https://drive.google.com/drive/folders/{folderId}
+ * - https://drive.google.com/drive/u/0/folders/{folderId}
+ * - https://docs.google.com/document/d/{fileId}/edit
+ * - https://docs.google.com/document/d/{fileId}
+ * - https://drive.google.com/file/d/{fileId}/view
+ * - https://drive.google.com/open?id={fileId}
+ * - Direct file ID or folder ID (returns as-is)
+ *
+ * @param urlOrId - Google Drive/Docs URL or file ID
+ * @returns The extracted file ID
+ * @throws Error if the URL format is not recognized
+ */
+export function extractFileId(urlOrId: string): string {
+  // If it's already a file ID (no slashes or special characters), return as-is
+  if (
+    !urlOrId.includes("/") &&
+    !urlOrId.includes("?") &&
+    !urlOrId.includes("&")
+  ) {
+    return urlOrId;
+  }
+
+  // Try to extract from various URL patterns
+  const patterns = [
+    // drive.google.com/drive/folders/{folderId}
+    // drive.google.com/drive/u/0/folders/{folderId}
+    /\/folders\/([a-zA-Z0-9_-]+)/,
+    // docs.google.com/document/d/{fileId}
+    /\/document\/d\/([a-zA-Z0-9_-]+)/,
+    // drive.google.com/file/d/{fileId}
+    /\/file\/d\/([a-zA-Z0-9_-]+)/,
+    // drive.google.com/open?id={fileId}
+    /[?&]id=([a-zA-Z0-9_-]+)/,
+    // Any URL with /d/{fileId} pattern
+    /\/d\/([a-zA-Z0-9_-]+)/,
+  ];
+
+  for (const pattern of patterns) {
+    const match = urlOrId.match(pattern);
+    if (match && match[1]) {
+      return match[1];
+    }
+  }
+
+  // If no pattern matches, assume it's a file ID (might be invalid, but let the API handle it)
+  return urlOrId;
+}
+
+/**
+ * Opens a Google Doc by ID or URL
+ *
+ * @param gsuiteUser - GSuite user instance
+ * @param documentIdOrUrl - Document ID or URL
+ * @returns Promise<Document> - Opened document instance
+ */
+export async function openDocument(
+  gsuiteUser: GSuiteUser,
+  documentIdOrUrl: string
+): Promise<Document> {
+  const extractedId = extractFileId(documentIdOrUrl);
+  const documents = gsuiteUser.documents();
+  return documents.open(extractedId);
+}
+
+/**
+ * Opens a spreadsheet and returns the first sheet
+ *
+ * @param gsuiteUser - GSuite user instance
+ * @param spreadsheetIdOrUrl - Spreadsheet ID or URL
+ * @returns Promise with spreadsheet and first sheet
+ * @throws Error if spreadsheet has no sheets
+ */
+export async function openSpreadsheetFirstSheet(
+  gsuiteUser: GSuiteUser,
+  spreadsheetIdOrUrl: string
+): Promise<{
+  spreadsheet: Spreadsheet;
+  sheet: Sheet;
+  spreadsheets: Spreadsheets;
+}> {
+  const extractedId = extractFileId(spreadsheetIdOrUrl);
+  const spreadsheets = gsuiteUser.spreadsheets();
+  const spreadsheet = await spreadsheets.open(extractedId);
+  const firstSheet = spreadsheet.sheets[0];
+  if (!firstSheet) {
+    throw new Error("Spreadsheet has no sheets");
+  }
+  return { spreadsheet, sheet: firstSheet, spreadsheets };
+}

package/http-server/HttpServer.ts

@@ -0,0 +1,110 @@
+/**
+ * HttpServer - Abstract HTTP server interface
+ *
+ * This interface defines the contract for HTTP server implementations.
+ * Currently, only NativeHttpServer is implemented using Node's native http module.
+ */
+
+import { ScratchEndpointDefinition, ScratchContext } from "../index";
+
+export interface HttpServer {
+  /**
+   * Start the HTTP server
+   * @param port - Port to listen on
+   * @returns Promise that resolves when server is ready
+   */
+  start(port: number): Promise<void>;
+
+  /**
+   * Stop the HTTP server
+   * @returns Promise that resolves when server is stopped
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Get the fetch handler for the server (for Bun/Cloudflare Workers)
+   * @returns Fetch handler function
+   */
+  getFetchHandler(): (request: Request) => Promise<Response>;
+
+  /**
+   * Register static file serving
+   * @param rootPath - Root path for static files
+   */
+  registerStaticFiles(rootPath: string): void;
+
+  /**
+   * Load endpoints from a directory
+   * @param directoryPath - Absolute path to directory containing endpoint files
+   */
+  loadEndpointsFromDirectory(directoryPath: string): Promise<void>;
+
+  /**
+   * Get all endpoint definitions
+   */
+  getAllEndpoints(): ScratchEndpointDefinition[];
+
+  /**
+   * Register all Scratch endpoints
+   * @param endpoints - Array of endpoint definitions
+   */
+  registerEndpoints(endpoints: ScratchEndpointDefinition[]): Promise<void>;
+
+  /**
+   * Get all registered endpoints (for logging/debugging)
+   */
+  getRegisteredEndpoints(): Promise<
+    Array<{
+      method: string;
+      endpoint: string;
+      blockType: string;
+      auth: string;
+      text: string;
+    }>
+  >;
+
+  /**
+   * Get endpoint handlers as an object keyed by opcode
+   */
+  getEndpointHandlers(): Promise<
+    Record<string, (context: any) => Promise<any>>
+  >;
+
+  /**
+   * Get handler by opcode
+   */
+  getHandler(
+    opcode: string
+  ): Promise<
+    | ((
+        context: ScratchContext,
+        query?: Record<string, string>,
+        requestBody?: any,
+        authHeader?: string
+      ) => Promise<any>)
+    | undefined
+  >;
+
+  /**
+   * Register an endpoint from TypeScript source code (PUT operation - always overwrites)
+   * @param source - TypeScript source code for the endpoint
+   * @returns Promise that resolves with registration result
+   */
+  registerEndpoint(source: string): Promise<{
+    success: boolean;
+    opcode?: string;
+    message?: string;
+    error?: string;
+  }>;
+
+  /**
+   * Remove an endpoint by opcode (DELETE operation)
+   * @param opcode - The opcode of the endpoint to remove
+   * @returns Promise that resolves with removal result
+   */
+  removeEndpoint(opcode: string): Promise<{
+    success: boolean;
+    message?: string;
+    error?: string;
+  }>;
+}