@goscribe/server 1.2.0 → 1.3.1

package/src/context.ts

@@ -17,4 +17,7 @@ export async function createContext({ req, res }: CreateExpressContextOptions) {
   return { db: prisma, session: null, req, res, cookies };
 }
 
-export type Context = Awaited<ReturnType<typeof createContext>>;
+/** Use `typeof prisma` for `db` so TS keeps generated model delegates (not a bare PrismaClient). */
+export type Context = Omit<Awaited<ReturnType<typeof createContext>>, "db"> & {
+  db: typeof prisma;
+};

package/src/lib/activity_human_description.test.ts

@@ -0,0 +1,28 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import {
+  getActivityHumanDescription,
+  getTrpcPathsMatchingDescriptionSearch,
+} from "./activity_human_description.js";
+
+test("description search resolves paths by label substring", () => {
+  const paths = getTrpcPathsMatchingDescriptionSearch("study streak");
+  assert.ok(paths.includes("workspace.getStudyAnalytics"));
+});
+
+test("known path returns curated label", () => {
+  assert.equal(
+    getActivityHumanDescription("workspace.getStudyAnalytics"),
+    "Loaded study streak and analytics"
+  );
+  assert.equal(
+    getActivityHumanDescription("payment.getUsageOverview"),
+    "Viewed plan usage and limits"
+  );
+});
+
+test("unknown path gets formatted fallback", () => {
+  const d = getActivityHumanDescription("someRouter.unknownProcedureName");
+  assert.ok(d.includes("Some Router"));
+  assert.ok(d.includes("Unknown"));
+});

package/src/lib/activity_human_description.ts

@@ -0,0 +1,239 @@
+/**
+ * User-facing labels for tRPC paths shown in activity logs.
+ * Unknown paths get a best-effort title from the procedure name.
+ */
+
+const PATH_LABELS: Record<string, string> = {
+  // Admin
+  "admin.getSystemStats": "Viewed system dashboard statistics",
+  "admin.listUsers": "Listed users (admin)",
+  "admin.listWorkspaces": "Listed workspaces (admin)",
+  "admin.updateUserRole": "Changed a user’s role",
+  "admin.listPlans": "Listed subscription plans",
+  "admin.upsertPlan": "Created or updated a plan",
+  "admin.deletePlan": "Deleted or deactivated a plan",
+  "admin.getUserInvoices": "Viewed a user’s invoices",
+  "admin.getUserDetailedInfo": "Viewed a user’s profile (admin)",
+  "admin.debugInvoices": "Ran invoice debug (admin)",
+  "admin.listResourcePrices": "Listed resource prices",
+  "admin.upsertResourcePrice": "Updated a resource price",
+  "admin.listRecentInvoices": "Viewed recent invoices",
+  "admin.activityList": "Viewed activity logs (admin)",
+  "admin.activityExportCsv": "Exported activity logs to CSV",
+  "admin.activityPurgeRetention": "Purged old activity logs (retention)",
+
+  // Workspace
+  "workspace.list": "Listed your workspaces",
+  "workspace.getTree": "Loaded folders and workspace tree",
+  "workspace.create": "Created a workspace",
+  "workspace.createFolder": "Created a folder",
+  "workspace.updateFolder": "Updated a folder",
+  "workspace.deleteFolder": "Deleted a folder",
+  "workspace.get": "Opened a workspace",
+  "workspace.getStats": "Loaded storage and usage stats",
+  "workspace.getStudyAnalytics": "Loaded study streak and analytics",
+  "workspace.update": "Updated workspace settings",
+  "workspace.delete": "Deleted a workspace",
+  "workspace.getFolderInformation": "Loaded folder details",
+  "workspace.getSharedWith": "Loaded who a workspace is shared with",
+  "workspace.uploadFiles": "Uploaded files",
+  "workspace.deleteFiles": "Deleted files",
+  "workspace.getFileUploadUrl": "Requested an upload URL",
+  "workspace.uploadAndAnalyzeMedia": "Uploaded and analyzed media",
+  "workspace.search": "Searched workspaces and content",
+
+  // Payment
+  "payment.getPlans": "Viewed available plans",
+  "payment.createCheckoutSession": "Started checkout",
+  "payment.confirmCheckoutSuccess": "Confirmed checkout",
+  "payment.createResourcePurchaseSession": "Started a resource purchase",
+  "payment.getUsageOverview": "Viewed plan usage and limits",
+  "payment.getResourcePrices": "Viewed resource prices",
+
+  // Notifications
+  "notifications.list": "Loaded notifications",
+  "notifications.unreadCount": "Checked unread notifications",
+  "notifications.markRead": "Marked a notification as read",
+  "notifications.markManyRead": "Marked notifications as read",
+  "notifications.markAllRead": "Marked all notifications as read",
+  "notifications.delete": "Deleted a notification",
+
+  // Members
+  "members.getMembers": "Listed workspace members",
+  "members.getCurrentUserRole": "Checked your role in a workspace",
+  "members.inviteMember": "Sent a workspace invite",
+  "members.getInvitations": "Listed pending invites",
+  "members.acceptInvite": "Accepted a workspace invite",
+  "members.changeMemberRole": "Changed a member’s role",
+  "members.removeMember": "Removed a workspace member",
+  "members.getPendingInvitations": "Listed invitations",
+  "members.cancelInvitation": "Canceled an invitation",
+  "members.resendInvitation": "Resent an invitation",
+  "members.getAllInvitationsDebug": "Listed invitations (debug)",
+  "member.acceptInvite": "Accepted a workspace invite",
+
+  // Flashcards
+  "flashcards.listSets": "Listed flashcard sets",
+  "flashcards.listCards": "Listed flashcards",
+  "flashcards.isGenerating": "Checked flashcard generation status",
+  "flashcards.createCard": "Created a flashcard",
+  "flashcards.updateCard": "Updated a flashcard",
+  "flashcards.gradeTypedAnswer": "Graded a flashcard answer",
+  "flashcards.deleteCard": "Deleted a flashcard",
+  "flashcards.deleteSet": "Deleted a flashcard set",
+  "flashcards.generateFromPrompt": "Generated flashcards from a prompt",
+  "flashcards.recordStudyAttempt": "Recorded a flashcard review",
+  "flashcards.getSetProgress": "Viewed flashcard progress",
+  "flashcards.getDueFlashcards": "Loaded due flashcards",
+  "flashcards.getSetStatistics": "Viewed flashcard statistics",
+  "flashcards.resetProgress": "Reset flashcard progress",
+  "flashcards.recordStudySession": "Recorded a study session",
+
+  // Worksheets
+  "worksheets.list": "Listed worksheets",
+  "worksheets.listPresets": "Listed worksheet presets",
+  "worksheets.createPreset": "Created a worksheet preset",
+  "worksheets.updatePreset": "Updated a worksheet preset",
+  "worksheets.deletePreset": "Deleted a worksheet preset",
+  "worksheets.create": "Created a worksheet",
+  "worksheets.get": "Opened a worksheet",
+  "worksheets.createWorksheetQuestion": "Added a worksheet question",
+  "worksheets.updateWorksheetQuestion": "Updated a worksheet question",
+  "worksheets.deleteWorksheetQuestion": "Deleted a worksheet question",
+  "worksheets.updateProblemStatus": "Updated worksheet problem status",
+  "worksheets.getProgress": "Viewed worksheet progress",
+  "worksheets.update": "Updated a worksheet",
+  "worksheets.delete": "Deleted a worksheet",
+  "worksheets.generateFromPrompt": "Generated a worksheet from a prompt",
+  "worksheets.checkAnswer": "Checked a worksheet answer",
+
+  // Podcast
+  "podcast.listEpisodes": "Listed podcast episodes",
+  "podcast.getEpisode": "Opened a podcast episode",
+  "podcast.generateEpisode": "Generated a podcast episode",
+  "podcast.deleteSegment": "Deleted a podcast segment",
+  "podcast.getEpisodeSchema": "Loaded podcast episode schema",
+  "podcast.updateEpisode": "Updated a podcast episode",
+  "podcast.deleteEpisode": "Deleted a podcast episode",
+  "podcast.getSegment": "Opened a podcast segment",
+  "podcast.getAvailableVoices": "Listed podcast voices",
+
+  // Study guide
+  "studyguide.get": "Opened or loaded a study guide",
+
+  // Chat
+  "chat.getChannels": "Listed chat channels",
+  "chat.getChannel": "Opened a chat channel",
+  "chat.removeChannel": "Removed a chat channel",
+  "chat.editChannel": "Renamed a chat channel",
+  "chat.createChannel": "Created a chat channel",
+  "chat.postMessage": "Sent a chat message",
+  "chat.editMessage": "Edited a chat message",
+  "chat.deleteMessage": "Deleted a chat message",
+
+  // Annotations
+  "annotations.listHighlights": "Listed study guide highlights",
+  "annotations.createHighlight": "Created a highlight",
+  "annotations.deleteHighlight": "Deleted a highlight",
+  "annotations.addComment": "Added a comment",
+  "annotations.updateComment": "Updated a comment",
+  "annotations.deleteComment": "Deleted a comment",
+
+  // Copilot
+  "copilot.listConversations": "Listed Copilot chats",
+  "copilot.getConversation": "Opened a Copilot chat",
+  "copilot.createConversation": "Started a Copilot chat",
+  "copilot.deleteConversation": "Deleted a Copilot chat",
+  "copilot.ask": "Sent a Copilot message",
+  "copilot.explainSelection": "Asked Copilot to explain a selection",
+  "copilot.suggestHighlights": "Asked Copilot for highlight suggestions",
+  "copilot.generateFlashcards": "Generated flashcards with Copilot",
+
+  // Auth (if ever logged)
+  "auth.updateProfile": "Updated profile",
+  "auth.uploadProfilePicture": "Uploaded a profile picture",
+  "auth.confirmProfileUpdate": "Confirmed profile update",
+  "auth.signup": "Created an account",
+  "auth.verifyEmail": "Verified email",
+  "auth.resendVerification": "Resent verification email",
+  "auth.login": "Signed in",
+  "auth.getSession": "Loaded session",
+  "auth.requestAccountDeletion": "Requested account deletion",
+  "auth.restoreAccount": "Restored account",
+  "auth.logout": "Signed out",
+};
+
+function splitCamelCase(s: string): string {
+  const spaced = s.replace(/([a-z])([A-Z])/g, "$1 $2");
+  return spaced.replace(/^\w/, (c) => c.toUpperCase());
+}
+
+const ROUTER_PREFIX: Record<string, string> = {
+  workspace: "Workspace",
+  payment: "Billing",
+  notifications: "Notifications",
+  admin: "Admin",
+  auth: "Account",
+  flashcards: "Flashcards",
+  worksheets: "Worksheets",
+  podcast: "Podcast",
+  studyguide: "Study guide",
+  chat: "Chat",
+  annotations: "Annotations",
+  copilot: "Copilot",
+  members: "Members",
+};
+
+function titleCaseRouter(router: string): string {
+  return ROUTER_PREFIX[router] ?? splitCamelCase(router);
+}
+
+/**
+ * Paths whose curated description contains `query` (case-insensitive).
+ * Used so activity log search matches human-readable text, not only raw paths.
+ */
+export function getTrpcPathsMatchingDescriptionSearch(query: string): string[] {
+  const q = query.trim().toLowerCase();
+  if (!q) return [];
+  const paths: string[] = [];
+  for (const [path, label] of Object.entries(PATH_LABELS)) {
+    if (label.toLowerCase().includes(q)) {
+      paths.push(path);
+    }
+  }
+  return paths;
+}
+
+/**
+ * Stable, human-readable line for UI and CSV exports.
+ */
+export function getActivityHumanDescription(
+  trpcPath: string | null | undefined,
+  actionFallback?: string | null
+): string {
+  const path = (trpcPath ?? "").trim();
+  if (path) {
+    const exact = PATH_LABELS[path];
+    if (exact) return exact;
+    const parts = path.split(".").filter(Boolean);
+    if (parts.length >= 2) {
+      const proc = parts[parts.length - 1]!;
+      const ns = parts[0]!;
+      const rest = parts.slice(1, -1);
+      const action = splitCamelCase(proc);
+      const area = titleCaseRouter(ns);
+      if (rest.length) {
+        return `${area} (${rest.join(" › ")}): ${action}`;
+      }
+      return `${area}: ${action}`;
+    }
+    return path;
+  }
+  const act = (actionFallback ?? "").replace(/^trpc\./, "");
+  if (act) {
+    const exact = PATH_LABELS[act];
+    if (exact) return exact;
+    return act.replace(/\./g, " › ");
+  }
+  return "Activity";
+}

package/src/lib/activity_log_service.test.ts

@@ -0,0 +1,37 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { ActivityLogCategory, ActivityLogStatus } from "@prisma/client";
+import {
+  buildActivityLogWhere,
+  inferCategoryFromTrpcPath,
+  redactSensitive,
+} from "./activity_log_service.js";
+
+test("redactSensitive redacts sensitive keys", () => {
+  const out = redactSensitive({
+    email: "a@b.com",
+    password: "secret",
+    nested: { authToken: "t", safe: 1 },
+  }) as Record<string, unknown>;
+  assert.equal(out.password, "[REDACTED]");
+  const nested = out.nested as Record<string, unknown>;
+  assert.equal(nested.authToken, "[REDACTED]");
+  assert.equal(nested.safe, 1);
+});
+
+test("inferCategoryFromTrpcPath maps routers", () => {
+  assert.equal(inferCategoryFromTrpcPath("auth.login"), ActivityLogCategory.AUTH);
+  assert.equal(inferCategoryFromTrpcPath("payment.checkout"), ActivityLogCategory.BILLING);
+  assert.equal(inferCategoryFromTrpcPath("admin.listUsers"), ActivityLogCategory.ADMIN);
+  assert.equal(inferCategoryFromTrpcPath("workspace.list"), ActivityLogCategory.WORKSPACE);
+  assert.equal(inferCategoryFromTrpcPath("flashcards.list"), ActivityLogCategory.CONTENT);
+});
+
+test("buildActivityLogWhere forces actor for user scope", () => {
+  const w = buildActivityLogWhere(
+    { status: ActivityLogStatus.SUCCESS },
+    { forceActorUserId: "user-1" }
+  );
+  assert.equal(w.actorUserId, "user-1");
+  assert.equal(w.status, ActivityLogStatus.SUCCESS);
+});

package/src/lib/activity_log_service.ts

@@ -0,0 +1,353 @@
+/**
+ * Activity log persistence (append-only). Env:
+ * - ACTIVITY_LOG_ENABLED=true|false (default true)
+ * - ACTIVITY_LOG_SAMPLE_RATE=0..1 (default 1)
+ * - ACTIVITY_LOG_RETENTION_DAYS (default 365; used by admin.activityPurgeRetention)
+ */
+import type { Prisma, PrismaClient } from "@prisma/client";
+import { ActivityLogCategory, ActivityLogStatus } from "@prisma/client";
+import type { IncomingMessage } from "node:http";
+import { logger } from "./logger.js";
+import { getTrpcPathsMatchingDescriptionSearch } from "./activity_human_description.js";
+
+const SENSITIVE_KEY_FRAGMENTS = [
+  "password",
+  "token",
+  "secret",
+  "authorization",
+  "cookie",
+  "credit",
+  "card",
+  "cvv",
+  "ssn",
+];
+
+export function isActivityLogEnabled(): boolean {
+  const v = process.env.ACTIVITY_LOG_ENABLED;
+  if (v === undefined || v === "") return true;
+  return v === "1" || v.toLowerCase() === "true";
+}
+
+function activitySampleRate(): number {
+  const raw = process.env.ACTIVITY_LOG_SAMPLE_RATE;
+  if (!raw) return 1;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n <= 0) return 0;
+  if (n > 1) return 1;
+  return n;
+}
+
+export function shouldSampleActivity(): boolean {
+  const rate = activitySampleRate();
+  if (rate >= 1) return true;
+  if (rate <= 0) return false;
+  return Math.random() < rate;
+}
+
+/** Recursive redaction for JSON-safe metadata (never log raw credentials). */
+export function redactSensitive(value: unknown): unknown {
+  if (value === null || value === undefined) return value;
+  if (typeof value === "string") {
+    if (value.length > 2000) return `${value.slice(0, 2000)}…[truncated]`;
+    return value;
+  }
+  if (typeof value !== "object") return value;
+  if (Array.isArray(value)) {
+    return value.map((v) => redactSensitive(v));
+  }
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
+    const lower = k.toLowerCase();
+    if (SENSITIVE_KEY_FRAGMENTS.some((f) => lower.includes(f))) {
+      out[k] = "[REDACTED]";
+      continue;
+    }
+    out[k] = redactSensitive(v);
+  }
+  return out;
+}
+
+export function inferCategoryFromTrpcPath(path: string): ActivityLogCategory {
+  const p = path.toLowerCase();
+  if (p.startsWith("auth.")) return ActivityLogCategory.AUTH;
+  if (p.startsWith("payment.")) return ActivityLogCategory.BILLING;
+  if (p.startsWith("admin.")) return ActivityLogCategory.ADMIN;
+  if (p.startsWith("workspace.") || p.startsWith("members.") || p.startsWith("member."))
+    return ActivityLogCategory.WORKSPACE;
+  if (
+    p.startsWith("flashcards.") ||
+    p.startsWith("worksheets.") ||
+    p.startsWith("studyguide.") ||
+    p.startsWith("podcast.") ||
+    p.startsWith("annotations.") ||
+    p.startsWith("chat.") ||
+    p.startsWith("copilot.")
+  )
+    return ActivityLogCategory.CONTENT;
+  if (p.startsWith("notifications.")) return ActivityLogCategory.SYSTEM;
+  return ActivityLogCategory.SYSTEM;
+}
+
+/** Best-effort workspace id from tRPC input (nested objects included). */
+export function extractWorkspaceIdFromInput(raw: unknown): string | undefined {
+  if (raw === null || raw === undefined) return undefined;
+  if (typeof raw === "object" && !Array.isArray(raw)) {
+    const o = raw as Record<string, unknown>;
+    const direct = o.workspaceId ?? o.workspace_id;
+    if (typeof direct === "string" && direct.length > 0) return direct;
+    for (const v of Object.values(o)) {
+      const nested = extractWorkspaceIdFromInput(v);
+      if (nested) return nested;
+    }
+  }
+  if (Array.isArray(raw)) {
+    for (const item of raw) {
+      const nested = extractWorkspaceIdFromInput(item);
+      if (nested) return nested;
+    }
+  }
+  return undefined;
+}
+
+export function truncateUserAgent(ua: string | undefined, max = 512): string | undefined {
+  if (!ua) return undefined;
+  return ua.length > max ? ua.slice(0, max) : ua;
+}
+
+export function getClientIp(req: IncomingMessage): string | undefined {
+  const xf = req.headers["x-forwarded-for"];
+  if (typeof xf === "string") return xf.split(",")[0]?.trim();
+  if (Array.isArray(xf)) return xf[0]?.split(",")[0]?.trim();
+  const ra = req.socket?.remoteAddress;
+  return ra ?? undefined;
+}
+
+export type RecordActivityInput = {
+  db: PrismaClient;
+  actorUserId: string;
+  actorEmailSnapshot?: string | null;
+  path: string;
+  type: "query" | "mutation" | "subscription";
+  status: ActivityLogStatus;
+  durationMs: number;
+  errorCode?: string | null;
+  rawInput?: unknown;
+  ipAddress?: string | null;
+  userAgent?: string | null;
+  httpMethod?: string | null;
+};
+
+export type RecordExplicitActivityInput = {
+  db: PrismaClient;
+  actorUserId?: string | null;
+  actorEmailSnapshot?: string | null;
+  /**
+   * A stable action label shown in admin UI/CSV.
+   * Example: `cron.purgeDeletedUsers`, `stripe.webhook.checkout.session.completed`
+   */
+  action: string;
+  category: ActivityLogCategory;
+  resourceType?: string | null;
+  resourceId?: string | null;
+  workspaceId?: string | null;
+  trpcPath?: string | null;
+  httpMethod?: string | null;
+  status: ActivityLogStatus;
+  errorCode?: string | null;
+  durationMs: number;
+  ipAddress?: string | null;
+  userAgent?: string | null;
+  metadata?: unknown;
+  /**
+   * When true, bypasses ACTIVITY_LOG_SAMPLE_RATE sampling.
+   * Useful for low-volume admin-auditable system events (cron/webhooks).
+   */
+  forceWrite?: boolean;
+};
+
+function buildMetadata(path: string, rawInput: unknown | undefined): Prisma.InputJsonValue | undefined {
+  if (rawInput === undefined) return undefined;
+  try {
+    const redacted = redactSensitive(rawInput) as Prisma.InputJsonValue;
+    return { trpcInputPreview: redacted };
+  } catch {
+    return { trpcInputPreview: "[unserializable]" };
+  }
+}
+
+function buildExplicitMetadata(metadata: unknown | undefined): Prisma.InputJsonValue | undefined {
+  if (metadata === undefined) return undefined;
+  try {
+    return redactSensitive(metadata) as Prisma.InputJsonValue;
+  } catch {
+    return { metadata: "[unserializable]" } as Prisma.InputJsonValue;
+  }
+}
+
+/**
+ * Persists one activity row. Prefer `scheduleRecordActivity` from request path to avoid blocking.
+ */
+export async function recordActivity(input: RecordActivityInput): Promise<void> {
+  if (!isActivityLogEnabled()) return;
+  if (!shouldSampleActivity()) return;
+
+  const category = inferCategoryFromTrpcPath(input.path);
+  const workspaceId = extractWorkspaceIdFromInput(input.rawInput) ?? undefined;
+  const action = `trpc.${input.path}`;
+  const metadata = buildMetadata(input.path, input.rawInput);
+
+  try {
+    await input.db.activityLog.create({
+      data: {
+        actorUserId: input.actorUserId,
+        actorEmailSnapshot: input.actorEmailSnapshot ?? undefined,
+        action,
+        category,
+        trpcPath: input.path,
+        httpMethod: input.httpMethod ?? undefined,
+        status: input.status,
+        errorCode: input.errorCode ?? undefined,
+        durationMs: input.durationMs,
+        workspaceId,
+        ipAddress: input.ipAddress ?? undefined,
+        userAgent: truncateUserAgent(input.userAgent ?? undefined),
+        metadata: metadata ?? undefined,
+      },
+    });
+  } catch (e) {
+    logger.error(
+      `ActivityLog write failed: ${e instanceof Error ? e.message : String(e)}`,
+      "ACTIVITY"
+    );
+  }
+}
+
+export function scheduleRecordActivity(input: RecordActivityInput): void {
+  void Promise.resolve()
+    .then(() => recordActivity(input))
+    .catch((e) =>
+      logger.error(
+        `ActivityLog async error: ${e instanceof Error ? e.message : String(e)}`,
+        "ACTIVITY"
+      )
+    );
+}
+
+/**
+ * Persists one explicit (non-tRPC) activity row.
+ * This is used for cron jobs, webhooks, and other system-wide background operations.
+ */
+export async function recordExplicitActivity(
+  input: RecordExplicitActivityInput
+): Promise<void> {
+  if (!isActivityLogEnabled()) return;
+  if (!input.forceWrite && !shouldSampleActivity()) return;
+
+  const metadata = buildExplicitMetadata(input.metadata);
+
+  try {
+    await input.db.activityLog.create({
+      data: {
+        actorUserId: input.actorUserId ?? undefined,
+        actorEmailSnapshot: input.actorEmailSnapshot ?? undefined,
+        action: input.action,
+        category: input.category,
+        resourceType: input.resourceType ?? undefined,
+        resourceId: input.resourceId ?? undefined,
+        workspaceId: input.workspaceId ?? undefined,
+        trpcPath: input.trpcPath ?? undefined,
+        httpMethod: input.httpMethod ?? undefined,
+        status: input.status,
+        errorCode: input.errorCode ?? undefined,
+        durationMs: input.durationMs,
+        ipAddress: input.ipAddress ?? undefined,
+        userAgent: truncateUserAgent(input.userAgent ?? undefined),
+        metadata: metadata ?? undefined,
+      },
+    });
+  } catch (e) {
+    logger.error(
+      `ActivityLog explicit write failed: ${
+        e instanceof Error ? e.message : String(e)
+      }`,
+      "ACTIVITY"
+    );
+  }
+}
+
+export function scheduleRecordExplicitActivity(
+  input: RecordExplicitActivityInput
+): void {
+  void Promise.resolve()
+    .then(() => recordExplicitActivity(input))
+    .catch((e) =>
+      logger.error(
+        `ActivityLog explicit async error: ${
+          e instanceof Error ? e.message : String(e)
+        }`,
+        "ACTIVITY"
+      )
+    );
+}
+
+/** Default retention: 365 days. Override with ACTIVITY_LOG_RETENTION_DAYS. */
+export function getActivityRetentionDays(): number {
+  const raw = process.env.ACTIVITY_LOG_RETENTION_DAYS;
+  if (!raw) return 365;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 1) return 365;
+  return Math.min(Math.floor(n), 3650);
+}
+
+export async function deleteActivityLogsOlderThan(
+  db: PrismaClient,
+  cutoff: Date
+): Promise<{ deleted: number }> {
+  const result = await db.activityLog.deleteMany({
+    where: { createdAt: { lt: cutoff } },
+  });
+  return { deleted: result.count };
+}
+
+export type ActivityLogFilter = {
+  actorUserId?: string;
+  workspaceId?: string;
+  from?: Date;
+  to?: Date;
+  category?: ActivityLogCategory;
+  status?: ActivityLogStatus;
+  search?: string;
+};
+
+export function buildActivityLogWhere(
+  filter: ActivityLogFilter,
+  options?: { forceActorUserId?: string }
+): Prisma.ActivityLogWhereInput {
+  const where: Prisma.ActivityLogWhereInput = {};
+  if (options?.forceActorUserId) {
+    where.actorUserId = options.forceActorUserId;
+  } else if (filter.actorUserId) {
+    where.actorUserId = filter.actorUserId;
+  }
+  if (filter.workspaceId) where.workspaceId = filter.workspaceId;
+  if (filter.category) where.category = filter.category;
+  if (filter.status) where.status = filter.status;
+  if (filter.from || filter.to) {
+    where.createdAt = {};
+    if (filter.from) where.createdAt.gte = filter.from;
+    if (filter.to) where.createdAt.lte = filter.to;
+  }
+  if (filter.search?.trim()) {
+    const s = filter.search.trim();
+    const pathsFromDescription = getTrpcPathsMatchingDescriptionSearch(s);
+    where.OR = [
+      { action: { contains: s, mode: "insensitive" } },
+      { trpcPath: { contains: s, mode: "insensitive" } },
+      { errorCode: { contains: s, mode: "insensitive" } },
+      ...(pathsFromDescription.length > 0
+        ? [{ trpcPath: { in: pathsFromDescription } }]
+        : []),
+    ];
+  }
+  return where;
+}