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

package/src/documents/classifier.ts

@@ -0,0 +1,61 @@
+/**
+ * Document title classifier. Products register their title patterns here;
+ * the documents service uses them to derive agent labels and the "report"
+ * filter. Kept free of the db import so client code and tests can load it.
+ */
+
+import { createRegistry } from "../registry";
+
+export type DocumentPatternEntry = {
+  /** Stable product slug — same one used across product configs. */
+  productSlug: string;
+  /** Human-readable agent label rendered in the documents UI. */
+  agentLabel: string;
+  /** Case-insensitive substring patterns; a document matches when its
+   *  title contains ANY of these, whatever the case of either. */
+  patterns: string[];
+};
+
+/**
+ * Keyed by product slug rather than appended, so a composition root that
+ * runs twice (or two copies of it) replaces the entry instead of matching
+ * the same patterns twice. Insertion order decides first-match
+ * classification.
+ */
+const registry = createRegistry<DocumentPatternEntry>("core/document-patterns");
+
+export function registerDocumentPatterns(entry: DocumentPatternEntry): void {
+  registry.set(entry.productSlug, entry);
+}
+
+export function classifyDocumentTitle(title: string): {
+  productSlug: string | null;
+  agentLabel: string;
+} {
+  const lower = title.toLowerCase();
+  for (const entry of registry.values()) {
+    if (entry.patterns.some((p) => lower.includes(p.toLowerCase()))) {
+      return { productSlug: entry.productSlug, agentLabel: entry.agentLabel };
+    }
+  }
+  return { productSlug: null, agentLabel: "AI Assistant" };
+}
+
+/** Returns true when the document looks like it belongs to any registered product. */
+export function isProductDocument(
+  title: string,
+  productSlug?: string
+): boolean {
+  const { productSlug: matched } = classifyDocumentTitle(title);
+  if (!matched) return false;
+  if (productSlug) return matched === productSlug;
+  return true;
+}
+
+export function listRegisteredDocumentPatterns(): readonly DocumentPatternEntry[] {
+  return [...registry.values()];
+}
+
+export function clearDocumentPatternRegistry(): void {
+  registry.clear();
+}

package/src/documents/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Thrown by the documents service for every failure it recognizes. Shaping
+ * it into a transport envelope is the caller's job.
+ */
+
+/**
+ * - `not_found` — no document (or no version of it) exists at the
+ *   given id within the actor's workspace/user scope.
+ * - `forbidden` — a document with this id exists but is owned by a
+ *   different user within the same workspace.
+ * - `invalid_input` — a caller-supplied argument failed a basic
+ *   invariant (e.g. an unparsable or out-of-window delete timestamp).
+ * - `database_error` — the underlying insert/update did not return the
+ *   row it was expected to.
+ */
+export type DocumentServiceErrorCode =
+  "not_found" | "forbidden" | "invalid_input" | "database_error";
+
+export class DocumentServiceError extends Error {
+  readonly code: DocumentServiceErrorCode;
+  // The ES2020 target predates `Error.cause`; declared so `err.cause`
+  // type-checks for callers.
+  readonly cause?: unknown;
+
+  constructor(
+    code: DocumentServiceErrorCode,
+    message: string,
+    options?: { cause?: unknown }
+  ) {
+    super(message);
+    this.name = "DocumentServiceError";
+    this.code = code;
+    if (options?.cause !== undefined) {
+      (this as { cause?: unknown }).cause = options.cause;
+    }
+    Object.setPrototypeOf(this, DocumentServiceError.prototype);
+  }
+}
+
+export function isDocumentServiceError(
+  error: unknown
+): error is DocumentServiceError {
+  return error instanceof DocumentServiceError;
+}

package/src/documents/index.ts

@@ -0,0 +1,24 @@
+export {
+  getUserDocuments,
+  getDocument,
+  getDocumentVersions,
+  saveDocument,
+  deleteDocumentVersions,
+} from "./service";
+
+export {
+  DocumentServiceError,
+  isDocumentServiceError,
+  type DocumentServiceErrorCode,
+} from "./errors";
+
+export type { DocumentActor, DocumentFilter, DocumentListItem } from "./types";
+
+export {
+  registerDocumentPatterns,
+  classifyDocumentTitle,
+  isProductDocument,
+  listRegisteredDocumentPatterns,
+  clearDocumentPatternRegistry,
+  type DocumentPatternEntry,
+} from "./classifier";

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";