@goscribe/server 1.6.0 → 1.7.0

package/dist/src/scripts/purge-deleted-users.js

@@ -0,0 +1,148 @@
+import { prisma as db } from '../lib/prisma.js';
+import { supabaseClient } from '../lib/storage.js';
+import { logger } from '../lib/logger.js';
+import { notifyAdminsAccountPermanentlyDeleted } from '../services/notifications/notification.service.js';
+import { ActivityLogCategory, ActivityLogStatus, } from '@prisma/client';
+import { recordExplicitActivity } from '../services/activity/activity-log.service.js';
+async function purgeDeletedUsers() {
+    try {
+        const startedAt = Date.now();
+        let status = ActivityLogStatus.SUCCESS;
+        let errorCode = null;
+        let purgedUsers = 0;
+        logger.info('Starting scheduled purge for deleted users...');
+        // Find users whose deletedAt is older than 30 days
+        const thirtyDaysAgo = new Date();
+        thirtyDaysAgo.setDate(thirtyDaysAgo.getDate() - 30);
+        const usersToPurge = await db.user.findMany({
+            where: {
+                deletedAt: {
+                    lte: thirtyDaysAgo,
+                },
+            },
+            select: {
+                id: true,
+                name: true,
+                email: true,
+                profilePicture: {
+                    select: {
+                        objectKey: true,
+                    }
+                }
+            },
+        });
+        if (usersToPurge.length === 0) {
+            logger.info('No users found past the 30-day grace period.');
+            await recordExplicitActivity({
+                db,
+                actorUserId: null,
+                action: 'cron.purgeDeletedUsers',
+                category: ActivityLogCategory.SYSTEM,
+                status: ActivityLogStatus.SUCCESS,
+                errorCode: null,
+                durationMs: Date.now() - startedAt,
+                forceWrite: true,
+                metadata: {
+                    usersFound: 0,
+                    usersPurged: 0,
+                    graceDays: 30,
+                },
+            });
+            return;
+        }
+        logger.info(`Found ${usersToPurge.length} user(s) to purge. Processing...`);
+        for (const user of usersToPurge) {
+            logger.info(`Purging user: ${user.id} (${user.email})`);
+            try {
+                // 1. Delete associated files from Supabase Storage
+                //    (Prisma cascade will delete the FileAsset DB record, but we need to delete the actual file first)
+                // Let's get all file assets owned by the user
+                const userFiles = await db.fileAsset.findMany({
+                    where: { userId: user.id },
+                    select: { objectKey: true, bucket: true },
+                });
+                for (const file of userFiles) {
+                    if (file.objectKey && file.bucket) {
+                        try {
+                            const { error } = await supabaseClient.storage
+                                .from(file.bucket)
+                                .remove([file.objectKey]);
+                            if (error) {
+                                logger.error(`Failed to delete file from Supabase: ${file.objectKey}`, error);
+                            }
+                            else {
+                                logger.info(`Deleted file from Supabase: ${file.objectKey}`);
+                            }
+                        }
+                        catch (storageError) {
+                            logger.error(`Exception during Supabase deletion for ${file.objectKey}:`, storageError);
+                        }
+                    }
+                }
+                await notifyAdminsAccountPermanentlyDeleted(db, {
+                    id: user.id,
+                    name: user.name,
+                    email: user.email,
+                }).catch(() => { });
+                // 2. Finally, delete the User from the database
+                //    (Prisma onDelete: Cascade will handle almost everything else depending on schema)
+                await db.user.delete({
+                    where: { id: user.id },
+                });
+                purgedUsers += 1;
+                logger.info(`Successfully purged user: ${user.id}`);
+            }
+            catch (userError) {
+                status = ActivityLogStatus.FAILURE;
+                errorCode =
+                    userError instanceof Error ? userError.message : String(userError);
+                logger.error(`Failed to purge user ${user.id}:`, userError);
+            }
+        }
+        if (status === ActivityLogStatus.SUCCESS) {
+            logger.info('Purge process completed successfully.');
+        }
+        else {
+            logger.warn('Purge process completed with failures.');
+        }
+        await recordExplicitActivity({
+            db,
+            actorUserId: null,
+            action: 'cron.purgeDeletedUsers',
+            category: ActivityLogCategory.SYSTEM,
+            status,
+            errorCode,
+            durationMs: Date.now() - startedAt,
+            forceWrite: true,
+            metadata: {
+                usersFound: usersToPurge.length,
+                usersPurged: purgedUsers,
+                graceDays: 30,
+            },
+        });
+    }
+    catch (error) {
+        const startedAt = Date.now();
+        await recordExplicitActivity({
+            db,
+            actorUserId: null,
+            action: 'cron.purgeDeletedUsers',
+            category: ActivityLogCategory.SYSTEM,
+            status: ActivityLogStatus.FAILURE,
+            errorCode: error instanceof Error ? error.message : String(error),
+            durationMs: Date.now() - startedAt,
+            forceWrite: true,
+        }).catch(() => { });
+        logger.error('Critical error during user purge process:', error);
+    }
+    finally {
+        await db.$disconnect();
+    }
+}
+// Run the script
+purgeDeletedUsers().then(() => {
+    process.exit(0);
+}).catch((error) => {
+    console.error("Unhandled error:", error);
+    process.exit(1);
+});

package/dist/src/server.d.ts

@@ -0,0 +1 @@
+import 'dotenv/config';

package/dist/src/server.js

@@ -0,0 +1,190 @@
+import 'dotenv/config';
+import express from 'express';
+import cors from 'cors';
+import helmet from 'helmet';
+import morgan from 'morgan';
+import compression from 'compression';
+import * as trpcExpress from '@trpc/server/adapters/express';
+import { appRouter } from './routers/_app.js';
+import { createContext } from './context.js';
+import { prisma } from './lib/prisma.js';
+import { logger } from './lib/logger.js';
+import { supabaseClient } from './lib/storage.js';
+import { ActivityLogCategory, ActivityLogStatus, } from '@prisma/client';
+import { recordExplicitActivity } from './services/activity/activity-log.service.js';
+const PORT = process.env.PORT ? Number(process.env.PORT) : 3001;
+async function main() {
+    const app = express();
+    // Middlewares
+    app.use(cors({
+        origin: ['https://www.scribe.study', 'https://scribe.study', 'http://localhost:3000', 'http://localhost:3002'],
+        credentials: true, // allow cookies
+        methods: ['GET', 'POST', 'PUT', 'DELETE', 'OPTIONS'],
+        allowedHeaders: ['Content-Type', 'Authorization', 'Cookie', 'Set-Cookie'],
+        exposedHeaders: ['Set-Cookie'],
+        preflightContinue: false, // Important: stop further handling of OPTIONS
+    }));
+    app.use(helmet());
+    // Custom morgan middleware with logger integration
+    app.use(morgan('combined', {
+        stream: {
+            write: (message) => {
+                logger.info(message.trim(), 'HTTP');
+            }
+        }
+    }));
+    app.use(compression());
+    // Stripe Webhook (Must be before express.json() for raw body)
+    app.post('/stripe/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+        const sig = req.headers['stripe-signature'];
+        const { stripe } = await import('./lib/stripe.js');
+        const { env } = await import('./lib/env.js');
+        const subscriptionService = await import('./services/billing/subscription.service.js');
+        let event;
+        try {
+            if (!sig || !env.STRIPE_WEBHOOK_SECRET) {
+                throw new Error('Missing stripe-signature or STRIPE_WEBHOOK_SECRET');
+            }
+            event = stripe?.webhooks.constructEvent(req.body, sig, env.STRIPE_WEBHOOK_SECRET);
+        }
+        catch (err) {
+            logger.error(`Webhook signature verification failed: ${err.message}`, 'STRIPE');
+            await recordExplicitActivity({
+                db: prisma,
+                actorUserId: null,
+                action: 'stripe.webhook.signatureVerificationFailed',
+                category: ActivityLogCategory.SYSTEM,
+                status: ActivityLogStatus.FAILURE,
+                errorCode: err?.message ?? 'unknown',
+                durationMs: 0,
+                forceWrite: true,
+            }).catch(() => { });
+            return res.status(400).send(`Webhook Error: ${err.message}`);
+        }
+        // Handle the event
+        try {
+            const startedAt = Date.now();
+            let status = ActivityLogStatus.SUCCESS;
+            let errorCode = null;
+            // Best-effort: some webhook objects include metadata.userId
+            let actorUserId = undefined;
+            try {
+                const obj = event?.data?.object;
+                const md = obj?.metadata;
+                if (md && typeof md.userId === 'string')
+                    actorUserId = md.userId;
+            }
+            catch {
+                actorUserId = undefined;
+            }
+            switch (event?.type) {
+                case 'checkout.session.completed':
+                    await subscriptionService.handleCheckoutCompleted(event);
+                    break;
+                case 'customer.subscription.created':
+                    await subscriptionService.handleSubscriptionCreated(event);
+                    break;
+                case 'customer.subscription.updated':
+                    await subscriptionService.handleSubscriptionUpdated(event);
+                    break;
+                case 'customer.subscription.deleted':
+                    await subscriptionService.handleSubscriptionDeleted(event);
+                    break;
+                case 'invoice.paid':
+                case 'invoice.payment_succeeded':
+                    await subscriptionService.handleInvoicePaid(event);
+                    break;
+                case 'invoice.payment_failed':
+                    await subscriptionService.handlePaymentFailed(event);
+                    break;
+                case 'payment_intent.payment_failed':
+                    await subscriptionService.handlePaymentIntentFailed(event);
+                    break;
+                default:
+                    logger.debug(`Unhandled stripe event type: ${event?.type}`, 'STRIPE');
+            }
+            await recordExplicitActivity({
+                db: prisma,
+                actorUserId: actorUserId ?? undefined,
+                action: `stripe.webhook.${event?.type}`,
+                category: ActivityLogCategory.SYSTEM,
+                status,
+                errorCode,
+                durationMs: Date.now() - startedAt,
+                forceWrite: true,
+                metadata: {
+                    stripeEventId: event?.id,
+                    stripeEventType: event?.type,
+                },
+            }).catch(() => { });
+            res.json({ received: true });
+        }
+        catch (err) {
+            const startedAt = Date.now();
+            const message = err?.message ?? 'unknown';
+            await recordExplicitActivity({
+                db: prisma,
+                actorUserId: null,
+                action: `stripe.webhook.${event?.type}`,
+                category: ActivityLogCategory.SYSTEM,
+                status: ActivityLogStatus.FAILURE,
+                errorCode: message,
+                durationMs: Date.now() - startedAt,
+                forceWrite: true,
+                metadata: {
+                    stripeEventId: event?.id,
+                    stripeEventType: event?.type,
+                },
+            }).catch(() => { });
+            logger.error(`Error processing webhook event ${event?.type}: ${err.message}`, 'STRIPE');
+            res.status(500).send('Internal Server Error');
+        }
+    });
+    app.use(express.json({ limit: '50mb' }));
+    app.use(express.urlencoded({ limit: '50mb', extended: true }));
+    // Health (plain Express)
+    app.get('/', (_req, res) => {
+        res.json({ ok: true, service: 'trpc-express', ts: Date.now() });
+    });
+    app.get('/profile-picture/:objectKey', async (req, res) => {
+        try {
+            const { objectKey } = req.params;
+            const { data, error } = await supabaseClient.storage
+                .from('media')
+                .download(objectKey);
+            if (error || !data) {
+                logger.error(`Failed to download profile picture: ${error?.message}`, 'STORAGE');
+                return res.status(404).send('Not found');
+            }
+            const buffer = Buffer.from(await data.arrayBuffer());
+            res.setHeader('Content-Type', 'image/jpeg');
+            res.setHeader('Cache-Control', 'public, max-age=31536000');
+            res.setHeader('Cross-Origin-Resource-Policy', 'cross-origin');
+            res.send(buffer);
+        }
+        catch (err) {
+            logger.error('Error serving profile picture', 'STORAGE', undefined, err);
+            res.status(500).send('Internal Server Error');
+        }
+    });
+    // tRPC mounted under /trpc
+    app.use('/trpc', trpcExpress.createExpressMiddleware({
+        router: appRouter,
+        createContext,
+    }));
+    app.listen(PORT, async () => {
+        logger.info(`Server ready on http://localhost:${PORT}`, 'SERVER');
+        logger.info(`tRPC endpoint at http://localhost:${PORT}/trpc`, 'SERVER');
+        try {
+            const { ensureCuratedKbCatalog } = await import('./lib/ensure-curated-kb-catalog.js');
+            await ensureCuratedKbCatalog(prisma);
+        }
+        catch (err) {
+            logger.error('Failed to seed curated knowledge bases', 'KB', undefined, err instanceof Error ? err : undefined);
+        }
+    });
+}
+main().catch((err) => {
+    logger.error('Failed to start server', 'SERVER', undefined, err);
+    process.exit(1);
+});

package/dist/src/services/activity/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/src/services/activity/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/src/services/activity/activity-human-description.service.test.d.ts

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

package/dist/src/services/activity/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"));
+});