@divizend/scratch-core 1.0.0

package/index.ts

@@ -0,0 +1,24 @@
+/**
+ * AI Executive - Intelligent Email Management and Processing System
+ *
+ * This is the main entry point for the AI Executive system, which provides:
+ * - Gmail integration with advanced email processing capabilities
+ * - AI-powered email analysis and response generation
+ * - Workflow automation for business processes
+ * - Database management for email fragments and metadata
+ *
+ * The system is designed to handle enterprise-scale email management
+ * with intelligent automation and AI assistance.
+ *
+ * @module AI Executive
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export * from "./basic";
+export * from "./core";
+export * from "./gsuite";
+export * from "./http-server";
+export * from "./resend";
+export * from "./s2";
+export * from "./queue";

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@divizend/scratch-core",
+  "version": "1.0.0",
+  "description": "Core library for Scratch endpoint system",
+  "main": "index.ts",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "**/*.ts"
+  ],
+  "scripts": {
+    "prepublishOnly": "echo 'Publishing @divizend/scratch-core'"
+  },
+  "dependencies": {
+    "@s2-dev/streamstore": "^0.18.1",
+    "cloudevents": "^10.0.0",
+    "google-auth-library": "^10.5.0",
+    "googleapis": "^167.0.0",
+    "jose": "^5.6.0",
+    "jsonpath-plus": "^10.3.0",
+    "marked": "^12.0.0",
+    "mustache": "^4.2.0",
+    "turndown": "^7.2.2"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.3",
+    "@types/mustache": "^4.2.6",
+    "@types/node": "^24.10.1",
+    "@types/turndown": "^5.0.6",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/queue/EmailQueue.ts

@@ -0,0 +1,228 @@
+import { RateLimiter } from "./RateLimiter";
+
+export interface QueuedEmail {
+  id: string;
+  from: string;
+  to: string;
+  subject: string;
+  content: string;
+  queuedAt: number;
+}
+
+export interface SendResult {
+  success: boolean;
+  sent: number;
+  errors: number;
+  message: string;
+}
+
+export interface EmailProfile {
+  /** Array of domains this profile handles */
+  domains: string[];
+  /** Function to send an email using this profile */
+  sendHandler: (email: QueuedEmail) => Promise<void>;
+  /** Optional function to get domains dynamically (for validation) */
+  getDomains?: () => Promise<string[]> | string[];
+}
+
+export class EmailQueue {
+  private queue: QueuedEmail[] = [];
+  private isSending = false;
+  private rateLimiter: RateLimiter;
+  private profiles: EmailProfile[];
+
+  constructor(profiles: EmailProfile[], rateLimitDelayMs: number = 100) {
+    this.profiles = profiles;
+    this.rateLimiter = new RateLimiter(rateLimitDelayMs);
+  }
+
+  /**
+   * Add an email to the queue
+   */
+  add(email: Omit<QueuedEmail, "id" | "queuedAt">): QueuedEmail {
+    const queuedEmail: QueuedEmail = {
+      ...email,
+      id: crypto.randomUUID(),
+      queuedAt: Date.now(),
+    };
+    this.queue.push(queuedEmail);
+    return queuedEmail;
+  }
+
+  /**
+   * Get all emails in the queue
+   */
+  getAll(): QueuedEmail[] {
+    return [...this.queue];
+  }
+
+  /**
+   * Get emails by IDs
+   */
+  getByIds(ids: string[]): QueuedEmail[] {
+    return this.queue.filter((email) => ids.includes(email.id));
+  }
+
+  /**
+   * Clear all emails from the queue
+   */
+  clear(): void {
+    this.queue.length = 0;
+  }
+
+  /**
+   * Remove emails by IDs
+   */
+  removeByIds(ids: string[]): number {
+    const initialLength = this.queue.length;
+    this.queue = this.queue.filter((email) => !ids.includes(email.id));
+    return initialLength - this.queue.length;
+  }
+
+  /**
+   * Check if emails are currently being sent
+   */
+  getIsSending(): boolean {
+    return this.isSending;
+  }
+
+  /**
+   * Get all domains from all profiles
+   */
+  async getAllDomains(): Promise<string[]> {
+    const allDomains: string[] = [];
+
+    for (const profile of this.profiles) {
+      if (profile.getDomains) {
+        const domains = await profile.getDomains();
+        allDomains.push(
+          ...(Array.isArray(domains) ? domains : await Promise.resolve(domains))
+        );
+      } else {
+        allDomains.push(...profile.domains);
+      }
+    }
+
+    return [...new Set(allDomains)]; // Remove duplicates
+  }
+
+  /**
+   * Find the profile that handles a given domain
+   */
+  private async findProfileForDomain(
+    domain: string
+  ): Promise<EmailProfile | null> {
+    for (const profile of this.profiles) {
+      let profileDomains: string[] = [];
+
+      if (profile.getDomains) {
+        const domains = await profile.getDomains();
+        profileDomains = Array.isArray(domains)
+          ? domains
+          : await Promise.resolve(domains);
+      } else {
+        profileDomains = profile.domains;
+      }
+
+      if (profileDomains.includes(domain)) {
+        return profile;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Validate that a domain is handled by one of the profiles
+   */
+  async validateDomain(domain: string): Promise<boolean> {
+    const profile = await this.findProfileForDomain(domain);
+    return profile !== null;
+  }
+
+  /**
+   * Send emails (all or selected by IDs)
+   * Routes emails to appropriate profile handlers based on sender domain
+   * @param ids - Array of email IDs to send, or null to send all
+   * @returns Send result with statistics
+   */
+  async send(ids: string[] | null): Promise<SendResult> {
+    if (this.isSending) {
+      throw new Error("Email sending already in progress");
+    }
+
+    // Always create a copy to avoid modifying the queue while iterating
+    const emailsToSend =
+      ids === null
+        ? [...this.queue] // Copy all emails
+        : this.getByIds(ids); // getByIds already returns a filtered copy
+
+    if (emailsToSend.length === 0) {
+      return {
+        success: true,
+        sent: 0,
+        errors: 0,
+        message: "No emails to send",
+      };
+    }
+
+    this.isSending = true;
+    let sent = 0;
+    let errors = 0;
+
+    try {
+      // Send emails with rate limiting
+      // emailsToSend is already a copy, so safe to iterate
+      await this.rateLimiter.process(emailsToSend, async (email) => {
+        try {
+          // Extract domain from sender email
+          const fromDomain = email.from.split("@")[1];
+          if (!fromDomain) {
+            throw new Error(`Invalid sender email: ${email.from}`);
+          }
+
+          // Find the profile that handles this domain
+          const profile = await this.findProfileForDomain(fromDomain);
+
+          if (!profile) {
+            // This should not happen since domain was validated when queuing
+            // But handle it gracefully just in case
+            errors++;
+            console.error(
+              `Unexpected: Unrecognized sender domain: ${fromDomain} for queued email ${email.id}. This should have been caught during validation.`
+            );
+            return;
+          }
+
+          // Send using the profile's handler
+          await profile.sendHandler(email);
+
+          sent++;
+          // Remove sent email from queue
+          const index = this.queue.findIndex((e) => e.id === email.id);
+          if (index !== -1) {
+            this.queue.splice(index, 1);
+          }
+        } catch (error) {
+          errors++;
+          console.error(
+            `Error processing email ${email.id}: ${
+              error instanceof Error ? error.message : String(error)
+            }`
+          );
+        }
+      });
+    } finally {
+      this.isSending = false;
+    }
+
+    return {
+      success: true,
+      sent,
+      errors,
+      message: `Sent ${sent} email(s)${
+        errors > 0 ? `, ${errors} error(s)` : ""
+      }`,
+    };
+  }
+}

package/queue/RateLimiter.ts

@@ -0,0 +1,54 @@
+/**
+ * Rate limiter utility for controlling the rate of operations
+ */
+export class RateLimiter {
+  private delayMs: number;
+
+  /**
+   * Create a new rate limiter
+   * @param delayMs - Delay in milliseconds between operations
+   */
+  constructor(delayMs: number) {
+    this.delayMs = delayMs;
+  }
+
+  /**
+   * Wait for the configured delay period
+   * @returns Promise that resolves after the delay
+   */
+  async wait(): Promise<void> {
+    return new Promise((resolve) => setTimeout(resolve, this.delayMs));
+  }
+
+  /**
+   * Get the delay in milliseconds
+   */
+  getDelay(): number {
+    return this.delayMs;
+  }
+
+  /**
+   * Process items with rate limiting
+   * @param items - Array of items to process
+   * @param processor - Async function to process each item
+   * @returns Array of results from processing each item
+   */
+  async process<T, R>(
+    items: T[],
+    processor: (item: T, index: number) => Promise<R>
+  ): Promise<R[]> {
+    const results: R[] = [];
+
+    for (let i = 0; i < items.length; i++) {
+      const result = await processor(items[i], i);
+      results.push(result);
+
+      // Wait before processing next item (except for the last one)
+      if (i < items.length - 1) {
+        await this.wait();
+      }
+    }
+
+    return results;
+  }
+}

package/queue/index.ts

@@ -0,0 +1,2 @@
+export * from "./EmailQueue";
+export * from "./RateLimiter";

package/resend/Resend.ts

@@ -0,0 +1,190 @@
+/**
+ * Resend - Email Service Adapter
+ *
+ * The Resend class provides an adapter for the Resend email service API,
+ * abstracting the HTTP calls and configuration.
+ *
+ * @class Resend
+ * @version 1.0.0
+ */
+
+import { envOr, envOrDefault } from "../index";
+
+export interface ResendEmailParams {
+  from: string;
+  to: string;
+  subject: string;
+  html: string;
+}
+
+export interface ResendResponse {
+  ok: boolean;
+  status: number;
+  text: string;
+}
+
+export interface ResendDomain {
+  id: string;
+  name: string;
+  status: string;
+  created_at: string;
+}
+
+export class Resend {
+  private apiKey: string;
+  private apiRoot: string;
+  private cachedDomains: string[] = [];
+
+  /**
+   * Private constructor - use Resend.construct() instead
+   *
+   * @param apiKey - Resend API key
+   * @param apiRoot - Resend API root URL
+   * @param domains - Pre-fetched domains array
+   */
+  private constructor(apiKey: string, apiRoot: string, domains: string[] = []) {
+    this.apiKey = apiKey;
+    this.apiRoot = apiRoot;
+    this.cachedDomains = domains;
+  }
+
+  /**
+   * Creates a new Resend instance and fetches domains once
+   * Automatically reads API key from RESEND_API_KEY environment variable
+   * and API root from RESEND_API_ROOT (defaults to "api.resend.com")
+   *
+   * @param apiKey - Optional Resend API key (overrides RESEND_API_KEY env var)
+   * @param apiRoot - Optional Resend API root URL (overrides RESEND_API_ROOT env var, defaults to "api.resend.com")
+   * @returns Promise<Resend> - Resend instance with domains cached
+   * @throws Error if API key is not provided and RESEND_API_KEY is not set
+   */
+  static async construct(apiKey?: string, apiRoot?: string): Promise<Resend> {
+    const key = envOr(
+      apiKey,
+      "RESEND_API_KEY",
+        "Resend API key is required. Provide it via parameter or RESEND_API_KEY environment variable."
+      );
+    const root = envOrDefault(apiRoot, "RESEND_API_ROOT", "api.resend.com");
+
+    // Fetch domains once during construction
+    let domains: string[] = [];
+    try {
+      domains = await Resend.fetchDomains(key, root);
+    } catch (error) {
+      console.warn(
+        "Failed to fetch Resend domains during construction:",
+        error
+      );
+      // Continue with empty array - domains can be empty if fetch fails
+    }
+
+    return new Resend(key, root, domains);
+  }
+
+  /**
+   * Fetches domains from Resend API
+   * Called once during construction
+   *
+   * @private
+   * @static
+   * @param apiKey - Resend API key
+   * @param apiRoot - Resend API root URL
+   * @returns Promise<string[]> - Array of domain names
+   */
+  private static async fetchDomains(
+    apiKey: string,
+    apiRoot: string
+  ): Promise<string[]> {
+    const url = `https://${apiRoot}/domains`;
+    const response = await fetch(url, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        "Content-Type": "application/json",
+      },
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`Failed to fetch Resend domains: ${text}`);
+    }
+
+    const data = (await response.json()) as { data?: ResendDomain[] };
+    const domains: ResendDomain[] = data.data || [];
+
+    // Extract domain names and filter by verified status
+    return domains
+      .filter((domain) => domain.status === "verified")
+      .map((domain) => domain.name);
+  }
+
+  /**
+   * Gets all cached domains from Resend
+   * Returns the domains that were fetched once during construction
+   *
+   * @returns string[] - Array of domain names (cached, synchronous)
+   */
+  getDomains(): string[] {
+    return this.cachedDomains;
+  }
+
+  /**
+   * Sends an email via Resend API
+   *
+   * @param params - Email parameters
+   * @returns Promise<ResendResponse> - Response from Resend API
+   */
+  async sendEmail(params: ResendEmailParams): Promise<ResendResponse> {
+    const url = `https://${this.apiRoot}/emails`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        from: params.from,
+        to: [params.to],
+        subject: params.subject,
+        html: params.html,
+      }),
+    });
+
+    const text = await response.text();
+
+    return {
+      ok: response.ok,
+      status: response.status,
+      text,
+    };
+  }
+
+  /**
+   * Checks the health of the Resend service
+   * Verifies connectivity by checking cached domains
+   *
+   * @returns { status: string; message: string; connected: boolean; domains?: number }
+   */
+  getHealth(): {
+    status: string;
+    message: string;
+    connected: boolean;
+    domains?: number;
+  } {
+    try {
+      const domains = this.getDomains();
+      return {
+        status: "ok",
+        message: "Resend connected",
+        connected: true,
+        domains: domains.length,
+      };
+    } catch (error) {
+      return {
+        status: "error",
+        message: error instanceof Error ? error.message : "Unknown error",
+        connected: false,
+      };
+    }
+  }
+}

package/resend/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Resend Module - Email Service Adapter
+ *
+ * This module provides an adapter for the Resend email service API.
+ *
+ * @module Resend
+ * @version 1.0.0
+ * @author Divizend GmbH
+ */
+
+export * from "./Resend";