@intelligo-dev/core 1.0.0-beta.1 → 1.0.0-beta.13

package/src/documents/service.ts

@@ -0,0 +1,256 @@
+/**
+ * Server-only persistence for AI-generated documents.
+ *
+ * Callers pass a resolved actor (workspaceId, userId); core cannot depend on
+ * `@intelligo-dev/auth`. Every query filters by both ids — the caller is
+ * never trusted to have done it. Failures throw `DocumentServiceError`.
+ */
+
+import { and, desc, eq, gt } from "drizzle-orm";
+import { db } from "../db";
+import { documents } from "../db/schema";
+import { classifyDocumentTitle, isProductDocument } from "./classifier";
+import { DocumentServiceError } from "./errors";
+import type { DocumentActor, DocumentFilter, DocumentListItem } from "./types";
+
+type DocumentRow = {
+  id: string;
+  title: string;
+  kind: string;
+  createdAt: Date;
+  content: string | null;
+  metadata?: unknown;
+};
+
+/**
+ * `metadata` is untyped `jsonb` written by whoever saved the document,
+ * so it is read defensively: anything that is not a non-empty string
+ * is no link at all.
+ */
+function conversationIdOf(metadata: unknown): string | null {
+  if (!metadata || typeof metadata !== "object") return null;
+  const value = (metadata as { conversationId?: unknown }).conversationId;
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+function toListItem(doc: DocumentRow): DocumentListItem {
+  return {
+    id: doc.id,
+    title: doc.title,
+    kind: doc.kind,
+    createdAt: doc.createdAt.toISOString(),
+    agentLabel: classifyDocumentTitle(doc.title).agentLabel,
+    content: doc.content,
+    conversationId: conversationIdOf(doc.metadata),
+  };
+}
+
+/**
+ * The latest version of each of the actor's documents, newest first.
+ */
+export async function getUserDocuments(
+  actor: DocumentActor,
+  filter?: DocumentFilter
+): Promise<DocumentListItem[]> {
+  const uniqueDocs = await db
+    .selectDistinctOn([documents.id])
+    .from(documents)
+    .where(
+      and(
+        eq(documents.workspaceId, actor.workspaceId),
+        eq(documents.userId, actor.userId)
+      )
+    )
+    .orderBy(documents.id, desc(documents.createdAt));
+
+  let result: DocumentListItem[] = uniqueDocs.map(toListItem);
+
+  const filterType = filter?.type ?? "all";
+  if (filterType !== "all") {
+    result =
+      filterType === "report"
+        ? result.filter((doc) => isProductDocument(doc.title))
+        : result.filter((doc) => doc.kind === filterType);
+  }
+
+  return result;
+}
+
+/**
+ * The latest version of one document, scoped to the actor.
+ * Throws DocumentServiceError("not_found") if no such document exists.
+ */
+export async function getDocument(
+  actor: DocumentActor,
+  id: string
+): Promise<DocumentListItem> {
+  const [doc] = await db
+    .selectDistinctOn([documents.id])
+    .from(documents)
+    .where(
+      and(
+        eq(documents.id, id),
+        eq(documents.workspaceId, actor.workspaceId),
+        eq(documents.userId, actor.userId)
+      )
+    )
+    .orderBy(documents.id, desc(documents.createdAt));
+
+  if (!doc) {
+    throw new DocumentServiceError("not_found", "Document not found");
+  }
+
+  return toListItem(doc);
+}
+
+/**
+ * Every version of a document, newest first — what a canvas version
+ * picker walks. Throws ("not_found") when the actor has no such id.
+ */
+export async function getDocumentVersions(
+  actor: DocumentActor,
+  id: string
+): Promise<DocumentListItem[]> {
+  const rows = await db
+    .select()
+    .from(documents)
+    .where(
+      and(
+        eq(documents.id, id),
+        eq(documents.workspaceId, actor.workspaceId),
+        eq(documents.userId, actor.userId)
+      )
+    )
+    .orderBy(desc(documents.createdAt));
+
+  if (rows.length === 0) {
+    throw new DocumentServiceError("not_found", "Document not found");
+  }
+  return rows.map(toListItem);
+}
+
+/**
+ * Saves a document as a new version.
+ * Throws DocumentServiceError("forbidden") if a document with this id
+ * already exists in the workspace under a different user.
+ */
+export async function saveDocument(
+  actor: DocumentActor,
+  params: {
+    id: string;
+    title: string;
+    content: string;
+    kind: string;
+    /**
+     * The conversation this was written in, stored on `metadata` so
+     * the artifacts page can link back to it. Optional: a document
+     * saved by a job or an import belongs to no conversation.
+     */
+    conversationId?: string;
+  }
+): Promise<DocumentListItem> {
+  const existingDocs = await db
+    .select()
+    .from(documents)
+    .where(
+      and(
+        eq(documents.id, params.id),
+        eq(documents.workspaceId, actor.workspaceId)
+      )
+    );
+
+  if (existingDocs.length > 0) {
+    const firstDoc = existingDocs[0];
+    if (firstDoc && firstDoc.userId !== actor.userId) {
+      throw new DocumentServiceError(
+        "forbidden",
+        "Document belongs to a different user"
+      );
+    }
+  }
+
+  // Every save writes a new version row, so an edit that does not resend
+  // the conversation link would drop it. Carry the known one forward.
+  const conversationId =
+    params.conversationId ??
+    existingDocs.map((doc) => conversationIdOf(doc.metadata)).find(Boolean) ??
+    null;
+
+  const [newDocument] = await db
+    .insert(documents)
+    .values({
+      id: params.id,
+      userId: actor.userId,
+      workspaceId: actor.workspaceId,
+      title: params.title,
+      content: params.content,
+      kind: params.kind,
+      createdAt: new Date(),
+      metadata: conversationId ? { conversationId } : null,
+    })
+    .returning();
+
+  if (!newDocument) {
+    throw new DocumentServiceError("database_error", "Failed to save document");
+  }
+
+  return toListItem(newDocument);
+}
+
+const MAX_DELETE_WINDOW_DAYS = 30;
+
+/**
+ * Delete all versions of a document created after `timestamp`.
+ * Throws DocumentServiceError("invalid_input") for an unparsable
+ * timestamp or one older than the delete window, and ("not_found") if
+ * no document exists at that id within the actor's scope.
+ */
+export async function deleteDocumentVersions(
+  actor: DocumentActor,
+  id: string,
+  timestamp: string
+): Promise<DocumentListItem[]> {
+  const parsedTimestamp = new Date(timestamp);
+  if (Number.isNaN(parsedTimestamp.getTime())) {
+    throw new DocumentServiceError("invalid_input", "Invalid timestamp");
+  }
+
+  const oldestAllowed = new Date(
+    Date.now() - MAX_DELETE_WINDOW_DAYS * 24 * 60 * 60 * 1000
+  );
+  if (parsedTimestamp < oldestAllowed) {
+    throw new DocumentServiceError(
+      "invalid_input",
+      `timestamp must be within the last ${MAX_DELETE_WINDOW_DAYS} days`
+    );
+  }
+
+  const existingDocs = await db
+    .select()
+    .from(documents)
+    .where(
+      and(
+        eq(documents.id, id),
+        eq(documents.workspaceId, actor.workspaceId),
+        eq(documents.userId, actor.userId)
+      )
+    );
+
+  if (existingDocs.length === 0) {
+    throw new DocumentServiceError("not_found", "Document not found");
+  }
+
+  const deletedDocs = await db
+    .delete(documents)
+    .where(
+      and(
+        eq(documents.id, id),
+        eq(documents.workspaceId, actor.workspaceId),
+        eq(documents.userId, actor.userId),
+        gt(documents.createdAt, parsedTimestamp)
+      )
+    )
+    .returning();
+
+  return deletedDocs.map(toListItem);
+}

package/src/documents/types.ts

@@ -0,0 +1,24 @@
+/** Resolved actor identity — every query is scoped to this pair. */
+export type DocumentActor = {
+  workspaceId: string;
+  userId: string;
+};
+
+export type DocumentFilter = {
+  type?: "all" | "report" | "text" | "code" | "sheet" | "image";
+};
+
+export type DocumentListItem = {
+  id: string;
+  title: string;
+  kind: string;
+  createdAt: string; // ISO string, so it serializes to the client
+  agentLabel: string;
+  content: string | null;
+  /**
+   * The conversation this document was written in, when known. Read from
+   * `metadata.conversationId` rather than a column: a document may also be
+   * written from a job or an import.
+   */
+  conversationId: string | null;
+};

package/src/email/brand.ts

@@ -0,0 +1,24 @@
+/**
+ * Whose emails these are. Every deployment sends as itself, so the name
+ * and the support address come from its environment, never from the
+ * framework:
+ *
+ * - `APP_NAME` — the product's name. Falls back to the display name in
+ *   `EMAIL_FROM` ("Acme <noreply@acme.com>" → "Acme").
+ * - `SUPPORT_EMAIL` — where a reader can write back. Without it the
+ *   footer offers no address rather than someone else's.
+ */
+export type EmailBrand = {
+  /** Empty when neither variable names one. */
+  name: string;
+  supportEmail: string | null;
+};
+
+export function emailBrand(): EmailBrand {
+  const from = process.env.EMAIL_FROM?.trim() ?? "";
+  const display = /^"?([^"<]+?)"?\s*</.exec(from)?.[1]?.trim() ?? "";
+  return {
+    name: process.env.APP_NAME?.trim() || display,
+    supportEmail: process.env.SUPPORT_EMAIL?.trim() || null,
+  };
+}

package/src/email/index.ts

@@ -0,0 +1,19 @@
+export {
+  sendEmail,
+  type SendEmailParams,
+  type SendEmailWithComponentParams,
+  type SendEmailResult,
+} from "./send";
+export {
+  getEmailProvider,
+  resetEmailProviderCache,
+  type EmailProvider,
+  type EmailProviderName,
+  type EmailSendParams,
+  type EmailTemplateRef,
+  ResendProvider,
+  LoopsProvider,
+  ConsoleProvider,
+} from "./provider";
+export * from "./templates";
+export * from "./senders";

package/src/email/provider.ts

@@ -0,0 +1,278 @@
+import { Resend } from "resend";
+
+// The provider is chosen at runtime from EMAIL_PROVIDER or the API keys set:
+//   - ResendProvider sends the rendered React Email HTML.
+//   - LoopsProvider sends by template id (Loops accepts no raw HTML).
+//   - ConsoleProvider is the development fallback when no key is set.
+
+/**
+ * Provider-neutral template descriptor attached to every framework email.
+ *
+ * HTML-capable providers (Resend) ignore it — they send the rendered HTML.
+ * Template-based providers (Loops) require it: `key` is resolved to the
+ * provider-side template id and `variables` become the template's dynamic
+ * data. Keys are stable framework identifiers, e.g. "verify-email".
+ */
+export interface EmailTemplateRef {
+  key: string;
+  variables?: Record<string, string | number>;
+}
+
+export interface EmailSendParams {
+  to: string | string[];
+  subject: string;
+  html: string;
+  from?: string;
+  replyTo?: string;
+  template?: EmailTemplateRef;
+}
+
+export interface EmailProvider {
+  send(params: EmailSendParams): Promise<{ id: string }>;
+}
+
+/** Error with an HTTP-ish status code so send.ts can decide retryability. */
+function statusError(message: string, statusCode: number): Error {
+  const err = new Error(message) as Error & { statusCode?: number };
+  err.statusCode = statusCode;
+  return err;
+}
+
+export class ResendProvider implements EmailProvider {
+  private client: Resend;
+
+  constructor(apiKey: string) {
+    this.client = new Resend(apiKey);
+  }
+
+  async send(params: EmailSendParams): Promise<{ id: string }> {
+    // A sender is an address on a domain the deployment verified with
+    // Resend, which only the deployment knows.
+    if (!params.from) {
+      throw statusError(
+        `No sender for "${params.subject}" — set EMAIL_FROM to an address on a domain verified with Resend, e.g. "Acme <noreply@acme.com>"`,
+        400
+      );
+    }
+    const { data, error } = await this.client.emails.send({
+      from: params.from,
+      to: Array.isArray(params.to) ? params.to : [params.to],
+      subject: params.subject,
+      html: params.html,
+      replyTo: params.replyTo,
+    });
+
+    if (error) {
+      const err = new Error(error.message) as Error & { statusCode?: number };
+      // Resend error names map to HTTP status categories
+      if (
+        error.name === "validation_error" ||
+        error.name === "missing_required_field"
+      ) {
+        err.statusCode = 400;
+      }
+      throw err;
+    }
+
+    return { id: data?.id ?? "unknown" };
+  }
+}
+
+// Loops transactional emails are designed in the Loops dashboard and sent by
+// template id — the API accepts no raw HTML and exactly one recipient per
+// call. Template keys resolve to ids through (in order):
+//   1. the `transactionalIds` map passed to the constructor
+//   2. env: LOOPS_TRANSACTIONAL_ID_<KEY> (key upper-snaked,
+//      e.g. "verify-email" → LOOPS_TRANSACTIONAL_ID_VERIFY_EMAIL)
+// `from`/`replyTo` are ignored — the sender is configured per template in
+// Loops itself.
+
+const LOOPS_API_URL = "https://app.loops.so/api/v1/transactional";
+
+export class LoopsProvider implements EmailProvider {
+  constructor(
+    private apiKey: string,
+    private transactionalIds?: Record<string, string>
+  ) {}
+
+  private resolveTransactionalId(key: string): string | undefined {
+    const mapped = this.transactionalIds?.[key];
+    if (mapped) {
+      return mapped;
+    }
+    const envName = `LOOPS_TRANSACTIONAL_ID_${key
+      .toUpperCase()
+      .replace(/-/g, "_")}`;
+    return process.env[envName];
+  }
+
+  async send(params: EmailSendParams): Promise<{ id: string }> {
+    const template = params.template;
+    if (!template) {
+      throw statusError(
+        `Loops requires a template key (subject: "${params.subject}") — Loops cannot send raw HTML. Use a framework sender or pass { template }.`,
+        400
+      );
+    }
+
+    const transactionalId = this.resolveTransactionalId(template.key);
+    if (!transactionalId) {
+      throw statusError(
+        `No Loops transactional id mapped for template "${template.key}". Set LOOPS_TRANSACTIONAL_ID_${template.key
+          .toUpperCase()
+          .replace(
+            /-/g,
+            "_"
+          )} or pass a transactionalIds map to LoopsProvider.`,
+        400
+      );
+    }
+
+    const recipients = Array.isArray(params.to) ? params.to : [params.to];
+
+    // Loops accepts one recipient per request. Sequential, so a failure
+    // surfaces with normal retry semantics in send.ts.
+    for (const email of recipients) {
+      const response = await fetch(LOOPS_API_URL, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.apiKey}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          transactionalId,
+          email,
+          dataVariables: template.variables ?? {},
+        }),
+      });
+
+      if (!response.ok) {
+        let detail = "";
+        try {
+          const body = (await response.json()) as {
+            message?: string;
+            error?: { message?: string };
+          };
+          detail = body.message ?? body.error?.message ?? "";
+        } catch {
+          // Non-JSON error body — status code alone is enough
+        }
+        throw statusError(
+          `Loops send failed (${response.status}) for template "${template.key}"${detail ? `: ${detail}` : ""}`,
+          response.status
+        );
+      }
+    }
+
+    // Loops returns { success: true } with no message id
+    return { id: `loops:${transactionalId}` };
+  }
+}
+
+export class ConsoleProvider implements EmailProvider {
+  async send(params: EmailSendParams): Promise<{ id: string }> {
+    const recipient = Array.isArray(params.to)
+      ? params.to.join(", ")
+      : params.to;
+
+    console.log(
+      `[Email] Would send to: ${recipient}, subject: ${params.subject}`
+    );
+
+    return { id: `console-${Date.now()}` };
+  }
+}
+
+export type EmailProviderName = "resend" | "loops" | "console";
+
+let cachedProvider: EmailProvider | null = null;
+
+/** Test-only: clear the cached provider so env changes take effect. */
+export function resetEmailProviderCache(): void {
+  cachedProvider = null;
+}
+
+/**
+ * The email provider for this environment, cached after the first call.
+ *
+ * Priority:
+ *   1. EMAIL_PROVIDER env var → explicit selection (with API key validation)
+ *   2. RESEND_API_KEY → ResendProvider (auto-detect; preferred because it can
+ *      send every framework email without per-template setup)
+ *   3. LOOPS_API_KEY  → LoopsProvider (auto-detect; needs
+ *      LOOPS_TRANSACTIONAL_ID_* mappings for the templates you use)
+ *   4. (none)         → ConsoleProvider
+ */
+export function getEmailProvider(): EmailProvider {
+  if (cachedProvider) {
+    return cachedProvider;
+  }
+
+  const explicit = process.env.EMAIL_PROVIDER?.toLowerCase();
+
+  if (explicit) {
+    cachedProvider = resolveExplicitProvider(explicit);
+    if (cachedProvider) {
+      return cachedProvider;
+    }
+    // Unknown value — warn and fall through to auto-detect
+    console.warn(
+      `[Email] Unknown EMAIL_PROVIDER="${process.env.EMAIL_PROVIDER}", falling back to auto-detect`
+    );
+  }
+
+  // Auto-detect from the API keys set
+  const resendKey = process.env.RESEND_API_KEY;
+  if (resendKey) {
+    console.log("[Email] Using Resend provider");
+    cachedProvider = new ResendProvider(resendKey);
+    return cachedProvider;
+  }
+
+  const loopsKey = process.env.LOOPS_API_KEY;
+  if (loopsKey) {
+    console.log("[Email] Using Loops provider");
+    cachedProvider = new LoopsProvider(loopsKey);
+    return cachedProvider;
+  }
+
+  console.log("[Email] Using console provider (no API key set)");
+  cachedProvider = new ConsoleProvider();
+  return cachedProvider;
+}
+
+/**
+ * Resolve an explicit EMAIL_PROVIDER value to a provider instance.
+ * Returns null for unknown values so the caller can fall through to auto-detect.
+ */
+function resolveExplicitProvider(provider: string): EmailProvider | null {
+  switch (provider) {
+    case "resend": {
+      const key = process.env.RESEND_API_KEY;
+      if (!key) {
+        console.warn(
+          "[Email] EMAIL_PROVIDER=resend but RESEND_API_KEY is not set, falling back to console"
+        );
+        return new ConsoleProvider();
+      }
+      console.log("[Email] Using Resend provider (explicit)");
+      return new ResendProvider(key);
+    }
+    case "loops": {
+      const key = process.env.LOOPS_API_KEY;
+      if (!key) {
+        console.warn(
+          "[Email] EMAIL_PROVIDER=loops but LOOPS_API_KEY is not set, falling back to console"
+        );
+        return new ConsoleProvider();
+      }
+      console.log("[Email] Using Loops provider (explicit)");
+      return new LoopsProvider(key);
+    }
+    case "console":
+      console.log("[Email] Using console provider (explicit)");
+      return new ConsoleProvider();
+    default:
+      return null;
+  }
+}