@goscribe/server 1.3.4 → 1.6.0

package/dist/services/activity/activity-log.service.test.js

@@ -0,0 +1,27 @@
+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 },
+    });
+    assert.equal(out.password, "[REDACTED]");
+    const nested = out.nested;
+    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/dist/services/activity-human-description.service.d.ts

@@ -0,0 +1,13 @@
+/**
+ * User-facing labels for tRPC paths shown in activity logs.
+ * Unknown paths get a best-effort title from the procedure name.
+ */
+/**
+ * Paths whose curated description contains `query` (case-insensitive).
+ * Used so activity log search matches human-readable text, not only raw paths.
+ */
+export declare function getTrpcPathsMatchingDescriptionSearch(query: string): string[];
+/**
+ * Stable, human-readable line for UI and CSV exports.
+ */
+export declare function getActivityHumanDescription(trpcPath: string | null | undefined, actionFallback?: string | null): string;

package/dist/services/activity-human-description.service.js

@@ -0,0 +1,221 @@
+/**
+ * User-facing labels for tRPC paths shown in activity logs.
+ * Unknown paths get a best-effort title from the procedure name.
+ */
+const PATH_LABELS = {
+    // 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) {
+    const spaced = s.replace(/([a-z])([A-Z])/g, "$1 $2");
+    return spaced.replace(/^\w/, (c) => c.toUpperCase());
+}
+const ROUTER_PREFIX = {
+    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) {
+    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) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return [];
+    const paths = [];
+    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, actionFallback) {
+    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/dist/services/activity-human-description.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/activity-human-description.service.test.js

@@ -0,0 +1,16 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { getActivityHumanDescription, getTrpcPathsMatchingDescriptionSearch, } from "./activity-human-description.service.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/dist/services/activity-log.service.d.ts

@@ -0,0 +1,87 @@
+/**
+ * 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";
+export declare function isActivityLogEnabled(): boolean;
+export declare function shouldSampleActivity(): boolean;
+/** Recursive redaction for JSON-safe metadata (never log raw credentials). */
+export declare function redactSensitive(value: unknown): unknown;
+export declare function inferCategoryFromTrpcPath(path: string): ActivityLogCategory;
+/** Best-effort workspace id from tRPC input (nested objects included). */
+export declare function extractWorkspaceIdFromInput(raw: unknown): string | undefined;
+export declare function truncateUserAgent(ua: string | undefined, max?: number): string | undefined;
+export declare function getClientIp(req: IncomingMessage): string | 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;
+};
+/**
+ * Persists one activity row. Prefer `scheduleRecordActivity` from request path to avoid blocking.
+ */
+export declare function recordActivity(input: RecordActivityInput): Promise<void>;
+export declare function scheduleRecordActivity(input: RecordActivityInput): void;
+/**
+ * Persists one explicit (non-tRPC) activity row.
+ * This is used for cron jobs, webhooks, and other system-wide background operations.
+ */
+export declare function recordExplicitActivity(input: RecordExplicitActivityInput): Promise<void>;
+export declare function scheduleRecordExplicitActivity(input: RecordExplicitActivityInput): void;
+/** Default retention: 365 days. Override with ACTIVITY_LOG_RETENTION_DAYS. */
+export declare function getActivityRetentionDays(): number;
+export declare function deleteActivityLogsOlderThan(db: PrismaClient, cutoff: Date): Promise<{
+    deleted: number;
+}>;
+export type ActivityLogFilter = {
+    actorUserId?: string;
+    workspaceId?: string;
+    from?: Date;
+    to?: Date;
+    category?: ActivityLogCategory;
+    status?: ActivityLogStatus;
+    search?: string;
+};
+export declare function buildActivityLogWhere(filter: ActivityLogFilter, options?: {
+    forceActorUserId?: string;
+}): Prisma.ActivityLogWhereInput;

package/dist/services/activity-log.service.js

@@ -0,0 +1,276 @@
+import { ActivityLogCategory } from "@prisma/client";
+import { logger } from "../lib/logger.js";
+import { getTrpcPathsMatchingDescriptionSearch } from "./activity-human-description.service.js";
+const SENSITIVE_KEY_FRAGMENTS = [
+    "password",
+    "token",
+    "secret",
+    "authorization",
+    "cookie",
+    "credit",
+    "card",
+    "cvv",
+    "ssn",
+];
+export function isActivityLogEnabled() {
+    const v = process.env.ACTIVITY_LOG_ENABLED;
+    if (v === undefined || v === "")
+        return true;
+    return v === "1" || v.toLowerCase() === "true";
+}
+function activitySampleRate() {
+    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() {
+    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) {
+    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 = {};
+    for (const [k, v] of Object.entries(value)) {
+        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) {
+    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) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    if (typeof raw === "object" && !Array.isArray(raw)) {
+        const o = raw;
+        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, max = 512) {
+    if (!ua)
+        return undefined;
+    return ua.length > max ? ua.slice(0, max) : ua;
+}
+export function getClientIp(req) {
+    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;
+}
+function buildMetadata(path, rawInput) {
+    if (rawInput === undefined)
+        return undefined;
+    try {
+        const redacted = redactSensitive(rawInput);
+        return { trpcInputPreview: redacted };
+    }
+    catch {
+        return { trpcInputPreview: "[unserializable]" };
+    }
+}
+function buildExplicitMetadata(metadata) {
+    if (metadata === undefined)
+        return undefined;
+    try {
+        return redactSensitive(metadata);
+    }
+    catch {
+        return { metadata: "[unserializable]" };
+    }
+}
+/**
+ * Persists one activity row. Prefer `scheduleRecordActivity` from request path to avoid blocking.
+ */
+export async function recordActivity(input) {
+    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) {
+    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) {
+    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) {
+    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() {
+    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, cutoff) {
+    const result = await db.activityLog.deleteMany({
+        where: { createdAt: { lt: cutoff } },
+    });
+    return { deleted: result.count };
+}
+export function buildActivityLogWhere(filter, options) {
+    const where = {};
+    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;
+}

package/dist/services/activity-log.service.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/services/activity-log.service.test.js

@@ -0,0 +1,27 @@
+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 },
+    });
+    assert.equal(out.password, "[REDACTED]");
+    const nested = out.nested;
+    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);
+});