@goscribe/server 1.5.0 → 1.7.0

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

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

package/dist/src/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/src/services/admin/admin.service.d.ts

@@ -0,0 +1,270 @@
+import type { PrismaClient } from '@prisma/client';
+import { ActivityLogCategory, ActivityLogStatus, ArtifactType, InvoiceType } from '@prisma/client';
+import { BaseService } from '../base.service.js';
+export interface ActivityFilters {
+    from?: Date;
+    to?: Date;
+    actorUserId?: string;
+    workspaceId?: string;
+    category?: ActivityLogCategory;
+    status?: ActivityLogStatus;
+    search?: string;
+}
+export interface ListUsersInput {
+    page: number;
+    pageSize: number;
+    search?: string;
+    emailVerified: 'all' | 'yes' | 'no';
+    joinedFrom?: Date;
+    joinedTo?: Date;
+}
+export interface ListInvoicesInput {
+    page: number;
+    pageSize: number;
+    search?: string;
+    status?: string;
+    type?: InvoiceType;
+    userId?: string;
+    from?: Date;
+    to?: Date;
+}
+export interface UpsertPlanInput {
+    id?: string;
+    name: string;
+    description?: string;
+    type: string;
+    price: number;
+    stripePriceId?: string;
+    interval: string | null;
+    active: boolean;
+    limits: {
+        maxStorageBytes: number;
+        maxWorksheets: number;
+        maxFlashcards: number;
+        maxPodcasts: number;
+        maxStudyGuides: number;
+    };
+}
+export declare class AdminService extends BaseService {
+    constructor(db: PrismaClient);
+    getSystemStats(): Promise<{
+        totalUsers: number;
+        totalWorkspaces: number;
+        totalSubscriptions: number;
+        revenue: number;
+        subscriptionRevenue: number;
+        topupRevenue: number;
+    }>;
+    listUsers(input: ListUsersInput): Promise<{
+        users: any[];
+        page: number;
+        pageSize: number;
+        totalCount: number;
+        totalPages: number;
+    }>;
+    listInvoices(input: ListInvoicesInput): Promise<{
+        items: any;
+        page: number;
+        pageSize: number;
+        totalCount: any;
+        totalPages: number;
+    }>;
+    listWorkspaces(input: {
+        limit: number;
+        cursor?: string | null;
+    }): Promise<{
+        workspaces: ({
+            owner: {
+                email: string | null;
+                name: string | null;
+            };
+        } & {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            ownerId: string;
+            title: string;
+            description: string | null;
+            icon: string;
+            color: string;
+            markerColor: string | null;
+            folderId: string | null;
+            fileBeingAnalyzed: boolean;
+            analysisProgress: import("@prisma/client/runtime/client").JsonValue | null;
+            needsAnalysis: boolean;
+        })[];
+        nextCursor: string | undefined;
+    }>;
+    updateUserRole(actorId: string, input: {
+        userId: string;
+        roleName: string;
+    }): Promise<{
+        id: string;
+        email: string | null;
+        stripe_customer_id: string | null;
+        name: string | null;
+        emailVerified: Date | null;
+        passwordHash: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+        fileAssetId: string | null;
+        roleId: string | null;
+        deletedAt: Date | null;
+    }>;
+    listPlans(): import("../../../generated/prisma/internal/prismaNamespace.js").PrismaPromise<({
+        limit: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            planId: string;
+            maxStorageBytes: bigint;
+            maxWorksheets: number;
+            maxFlashcards: number;
+            maxPodcasts: number;
+            maxStudyGuides: number;
+        } | null;
+    } & {
+        id: string;
+        name: string;
+        createdAt: Date;
+        description: string | null;
+        type: string;
+        active: boolean;
+        price: number;
+        stripePriceId: string;
+        interval: string | null;
+    })[]>;
+    upsertPlan(actorId: string, input: UpsertPlanInput): Promise<{
+        id: string;
+        name: string;
+        createdAt: Date;
+        description: string | null;
+        type: string;
+        active: boolean;
+        price: number;
+        stripePriceId: string;
+        interval: string | null;
+    }>;
+    deletePlan(actorId: string, id: string): Promise<{
+        success: boolean;
+        message: string;
+    }>;
+    getUserInvoices(input: {
+        userId: string;
+        limit?: number;
+    }): any;
+    getUserDetailedInfo(userId: string): Promise<{
+        totalSpent: number;
+        purchasedCredits: {
+            type: ArtifactType;
+            amount: number;
+        }[];
+        profilePicture: string | null;
+        role: {
+            id: string;
+            name: string;
+        } | null;
+        subscriptions: ({
+            plan: {
+                id: string;
+                name: string;
+                createdAt: Date;
+                description: string | null;
+                type: string;
+                active: boolean;
+                price: number;
+                stripePriceId: string;
+                interval: string | null;
+            };
+        } & {
+            userId: string;
+            id: string;
+            createdAt: Date;
+            planId: string;
+            stripeSubscriptionId: string;
+            stripeCustomerId: string | null;
+            status: string;
+            currentPeriodStart: Date;
+            currentPeriodEnd: Date;
+            cancelAt: Date | null;
+            canceledAt: Date | null;
+        })[];
+        _count: {
+            artifacts: number;
+            workspaces: number;
+        };
+        id: string;
+        email: string | null;
+        stripe_customer_id: string | null;
+        name: string | null;
+        emailVerified: Date | null;
+        passwordHash: string | null;
+        createdAt: Date;
+        updatedAt: Date;
+        fileAssetId: string | null;
+        roleId: string | null;
+        deletedAt: Date | null;
+    }>;
+    debugInvoices(): Promise<{
+        count: any;
+        all: any;
+    }>;
+    listResourcePrices(): import("../../../generated/prisma/internal/prismaNamespace.js").PrismaPromise<{
+        id: string;
+        updatedAt: Date;
+        resourceType: ArtifactType;
+        priceCents: number;
+    }[]>;
+    upsertResourcePrice(actorId: string, input: {
+        resourceType: ArtifactType;
+        priceCents: number;
+    }): Promise<{
+        id: string;
+        updatedAt: Date;
+        resourceType: ArtifactType;
+        priceCents: number;
+    }>;
+    listRecentInvoices(limit: number): Promise<any>;
+    activityList(input: ActivityFilters & {
+        page: number;
+        limit: number;
+    }): Promise<{
+        items: {
+            id: string;
+            createdAt: Date;
+            action: string;
+            description: string;
+            category: ActivityLogCategory;
+            trpcPath: string | null;
+            status: ActivityLogStatus;
+            durationMs: number;
+            errorCode: string | null;
+            ipAddress: string | null;
+            actor: {
+                id: string;
+                email: string | null;
+                name: string | null;
+            } | null;
+            workspace: {
+                id: string;
+                title: string;
+            } | null;
+            metadata: import("@prisma/client/runtime/client").JsonValue;
+        }[];
+        page: number;
+        pageSize: number;
+        totalCount: number;
+        totalPages: number;
+    }>;
+    activityExportCsv(input: ActivityFilters & {
+        maxRows: number;
+    }): Promise<{
+        csv: string;
+        count: number;
+    }>;
+    activityPurgeRetention(): Promise<{
+        deleted: number;
+        retentionDays: number;
+        cutoff: Date;
+    }>;
+}