@vantageos/vantage-crm-mcp 0.1.0

package/dist/convex/crm/onboarding.js

@@ -0,0 +1,185 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.needsOnboarding = exports.importContacts = exports.setupWorkspace = void 0;
+const server_1 = require("../_generated/server");
+const values_1 = require("convex/values");
+const workspace_1 = require("../lib/workspace");
+const _helpers_1 = require("./_helpers");
+// =============================================================================
+// ONBOARDING: WORKSPACE SETUP
+// =============================================================================
+/**
+ * Save workspace description, ICP tags, and pipeline stages in one shot.
+ * Called at the end of the onboarding flow.
+ */
+exports.setupWorkspace = (0, server_1.mutation)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        description: values_1.v.optional(values_1.v.string()),
+        icpTags: values_1.v.optional(values_1.v.array(values_1.v.string())),
+        pipelineStages: values_1.v.optional(values_1.v.array(values_1.v.object({
+            id: values_1.v.string(),
+            name: values_1.v.string(),
+            order: values_1.v.number(),
+        }))),
+    },
+    handler: async (ctx, args) => {
+        const { canWrite } = await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        const workspace = await ctx.db.get(args.workspaceId);
+        if (!workspace)
+            throw new Error('Workspace not found');
+        const patch = {
+            updatedAt: Date.now(),
+        };
+        if (args.description !== undefined) {
+            patch.description = args.description;
+        }
+        if (args.pipelineStages !== undefined) {
+            patch.pipelineStages = args.pipelineStages;
+        }
+        // Store ICP tags in workspace settings
+        if (args.icpTags !== undefined) {
+            const existingSettings = workspace.settings ?? {};
+            patch.settings = {
+                ...existingSettings,
+                icpTags: args.icpTags,
+            };
+        }
+        await ctx.db.patch(args.workspaceId, patch);
+        return args.workspaceId;
+    },
+});
+/**
+ * Batch import contacts from onboarding.
+ * Parses pre-processed contact data, deduplicates by email,
+ * and creates contacts + companies in batch.
+ */
+exports.importContacts = (0, server_1.mutation)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        contacts: values_1.v.array(values_1.v.object({
+            firstName: values_1.v.string(),
+            lastName: values_1.v.string(),
+            email: values_1.v.optional(values_1.v.string()),
+            companyDomain: values_1.v.optional(values_1.v.string()),
+        })),
+    },
+    handler: async (ctx, args) => {
+        const { clerkId, canWrite } = await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        const now = Date.now();
+        // Fetch existing contacts for deduplication
+        const existingContacts = await ctx.db
+            .query('contacts')
+            .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+            .take(5000);
+        const existingEmails = new Set(existingContacts
+            .filter((c) => c.email && c.isArchived !== true)
+            .map((c) => c.email.toLowerCase()));
+        // Track companies by domain to avoid duplicates
+        const companyMap = new Map(); // domain -> companyId
+        // Fetch existing companies
+        const existingCompanies = await ctx.db
+            .query('companies')
+            .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+            .take(5000);
+        for (const company of existingCompanies) {
+            if (company.domain && company.isArchived !== true) {
+                companyMap.set(company.domain.toLowerCase(), company._id);
+            }
+        }
+        let created = 0;
+        let skipped = 0;
+        for (const contact of args.contacts) {
+            // Deduplicate by email
+            if (contact.email && existingEmails.has(contact.email.toLowerCase())) {
+                skipped++;
+                continue;
+            }
+            // Create company if domain provided and not yet created
+            let companyId;
+            if (contact.companyDomain) {
+                const domain = contact.companyDomain.toLowerCase();
+                const existingCompanyId = companyMap.get(domain);
+                if (existingCompanyId) {
+                    companyId = existingCompanyId;
+                }
+                else {
+                    // Create a company from the domain
+                    const companyName = domain.split('.')[0];
+                    const capitalizedName = companyName.charAt(0).toUpperCase() + companyName.slice(1);
+                    const searchableText = (0, _helpers_1.buildCompanySearchText)({
+                        name: capitalizedName,
+                        domain,
+                    });
+                    const newCompanyId = await ctx.db.insert('companies', {
+                        name: capitalizedName,
+                        domain,
+                        workspaceId: args.workspaceId,
+                        ownerId: clerkId,
+                        searchableText,
+                        createdAt: now,
+                        updatedAt: now,
+                    });
+                    companyMap.set(domain, newCompanyId);
+                    companyId = newCompanyId;
+                }
+            }
+            // Resolve company name for search text
+            let companyName;
+            if (companyId) {
+                const company = await ctx.db.get(companyId);
+                companyName = company?.name;
+            }
+            const searchableText = (0, _helpers_1.buildContactSearchText)({
+                firstName: contact.firstName,
+                lastName: contact.lastName,
+                email: contact.email,
+            }, companyName);
+            await ctx.db.insert('contacts', {
+                firstName: contact.firstName,
+                lastName: contact.lastName,
+                email: contact.email,
+                type: 'lead',
+                companyId,
+                workspaceId: args.workspaceId,
+                ownerId: clerkId,
+                searchableText,
+                createdAt: now,
+                updatedAt: now,
+            });
+            if (contact.email) {
+                existingEmails.add(contact.email.toLowerCase());
+            }
+            created++;
+        }
+        return { created, skipped, total: args.contacts.length };
+    },
+});
+/**
+ * Check if workspace needs onboarding (has zero contacts).
+ */
+exports.needsOnboarding = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+    },
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const contacts = await ctx.db
+            .query('contacts')
+            .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+            .take(1);
+        const activeContacts = contacts.filter((c) => c.isArchived !== true);
+        // Also check if workspace has pipeline stages configured
+        const workspace = await ctx.db.get(args.workspaceId);
+        const hasPipeline = workspace?.pipelineStages && workspace.pipelineStages.length > 0;
+        return {
+            needsOnboarding: activeContacts.length === 0 && !hasPipeline,
+            hasContacts: activeContacts.length > 0,
+            hasPipeline: !!hasPipeline,
+        };
+    },
+});

package/dist/convex/crm/stats.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.conversionRate = exports.pipelineStats = void 0;
+const server_1 = require("../_generated/server");
+const values_1 = require("convex/values");
+const workspace_1 = require("../lib/workspace");
+// =============================================================================
+// CRM STATS & ANALYTICS
+// =============================================================================
+exports.pipelineStats = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+    },
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const deals = await ctx.db
+            .query('deals')
+            .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+            .take(1000);
+        const activeDeals = deals.filter((d) => d.isArchived !== true);
+        // Group by stage
+        const stageMap = new Map();
+        for (const deal of activeDeals) {
+            const existing = stageMap.get(deal.stage) ?? {
+                count: 0,
+                totalValue: 0,
+            };
+            existing.count += 1;
+            existing.totalValue += deal.value ?? 0;
+            stageMap.set(deal.stage, existing);
+        }
+        const stages = Array.from(stageMap.entries()).map(([stage, data]) => ({
+            stage,
+            count: data.count,
+            totalValue: data.totalValue,
+            avgDealSize: data.count > 0 ? data.totalValue / data.count : 0,
+        }));
+        return {
+            stages,
+            totalDeals: activeDeals.length,
+            totalValue: activeDeals.reduce((sum, d) => sum + (d.value ?? 0), 0),
+        };
+    },
+});
+exports.conversionRate = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        startDate: values_1.v.optional(values_1.v.number()),
+        endDate: values_1.v.optional(values_1.v.number()),
+    },
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const deals = await ctx.db
+            .query('deals')
+            .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+            .take(1000);
+        let filtered = deals.filter((d) => d.isArchived !== true);
+        // Apply date filters based on actualCloseDate
+        if (args.startDate) {
+            filtered = filtered.filter((d) => d.actualCloseDate && d.actualCloseDate >= args.startDate);
+        }
+        if (args.endDate) {
+            filtered = filtered.filter((d) => d.actualCloseDate && d.actualCloseDate <= args.endDate);
+        }
+        // Closed deals = those with an actualCloseDate
+        const closedDeals = filtered.filter((d) => d.actualCloseDate);
+        const wonDeals = closedDeals.filter((d) => !d.stage.toLowerCase().includes('lost'));
+        const rate = closedDeals.length > 0 ? wonDeals.length / closedDeals.length : 0;
+        return {
+            wonCount: wonDeals.length,
+            closedCount: closedDeals.length,
+            conversionRate: Math.round(rate * 10000) / 100, // percentage with 2 decimals
+        };
+    },
+});

package/dist/convex/crm/tasks.js

@@ -0,0 +1,109 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.overdue = exports.complete = exports.list = exports.create = void 0;
+const server_1 = require("../_generated/server");
+const values_1 = require("convex/values");
+const workspace_1 = require("../lib/workspace");
+// =============================================================================
+// TASKS (activities where type='task')
+// OQ-4: tasks are part of the activities audit trail — NO delete mutation.
+// =============================================================================
+exports.create = (0, server_1.mutation)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        subject: values_1.v.string(),
+        contactId: values_1.v.optional(values_1.v.id('contacts')),
+        dealId: values_1.v.optional(values_1.v.id('deals')),
+        companyId: values_1.v.optional(values_1.v.id('companies')),
+        dueAt: values_1.v.number(),
+        description: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('activities'),
+    handler: async (ctx, args) => {
+        const { clerkId, canWrite } = await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        const now = Date.now();
+        const activityId = await ctx.db.insert('activities', {
+            type: 'task',
+            subject: args.subject,
+            description: args.description,
+            contactId: args.contactId,
+            dealId: args.dealId,
+            companyId: args.companyId,
+            dueAt: args.dueAt,
+            workspaceId: args.workspaceId,
+            ownerId: clerkId,
+            occurredAt: now,
+            createdAt: now,
+            updatedAt: now,
+        });
+        return activityId;
+    },
+});
+exports.list = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        ownerId: values_1.v.optional(values_1.v.string()),
+        isCompleted: values_1.v.optional(values_1.v.boolean()),
+        dueBefore: values_1.v.optional(values_1.v.number()),
+    },
+    returns: values_1.v.array(values_1.v.any()),
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const activities = await ctx.db
+            .query('activities')
+            .withIndex('by_workspace_type', (q) => q.eq('workspaceId', args.workspaceId).eq('type', 'task'))
+            .order('desc')
+            .take(1000);
+        let filtered = activities;
+        if (args.ownerId !== undefined) {
+            filtered = filtered.filter((a) => a.ownerId === args.ownerId);
+        }
+        if (args.isCompleted !== undefined) {
+            filtered = filtered.filter((a) => args.isCompleted ? a.completedAt !== undefined : a.completedAt === undefined);
+        }
+        if (args.dueBefore !== undefined) {
+            filtered = filtered.filter((a) => a.dueAt !== undefined && a.dueAt < args.dueBefore);
+        }
+        return filtered;
+    },
+});
+exports.complete = (0, server_1.mutation)({
+    args: {
+        activityId: values_1.v.id('activities'),
+    },
+    returns: values_1.v.id('activities'),
+    handler: async (ctx, args) => {
+        const activity = await ctx.db.get(args.activityId);
+        if (!activity)
+            throw new Error('Task not found');
+        if (activity.type !== 'task')
+            throw new Error('Activity is not a task');
+        const { canWrite } = await (0, workspace_1.validateWorkspaceAccess)(ctx, activity.workspaceId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        await ctx.db.patch(args.activityId, {
+            completedAt: Date.now(),
+            updatedAt: Date.now(),
+        });
+        return args.activityId;
+    },
+});
+exports.overdue = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+    },
+    returns: values_1.v.array(values_1.v.any()),
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const now = Date.now();
+        const tasks = await ctx.db
+            .query('activities')
+            .withIndex('by_workspace_type', (q) => q.eq('workspaceId', args.workspaceId).eq('type', 'task'))
+            .take(1000);
+        return tasks.filter((t) => t.completedAt === undefined &&
+            t.dueAt !== undefined &&
+            t.dueAt < now);
+    },
+});

package/dist/convex/crons.js

@@ -0,0 +1,25 @@
+"use strict";
+/**
+ * Convex Cron Jobs
+ *
+ * Scheduled background tasks. Each cron calls an internalAction.
+ *
+ * Note: Calendar sync requires workspace-specific entityId.
+ * The cron triggers a dispatcher that iterates over workspaces
+ * with calendar sync enabled.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const server_1 = require("convex/server");
+const api_1 = require("./_generated/api");
+const crons = (0, server_1.cronJobs)();
+// =============================================================================
+// CALENDAR SYNC — every 5 minutes
+// Dispatches to all workspaces with Google Calendar connected.
+// =============================================================================
+crons.interval('calendar-sync-dispatch', { minutes: 5 }, api_1.internal.crm.calendarCronDispatch.dispatchCalendarSync);
+// =============================================================================
+// EMAIL SYNC — every 5 minutes
+// Dispatches to all workspaces with Gmail connected (emailSyncEnabled setting).
+// =============================================================================
+crons.interval('email-sync-dispatch', { minutes: 5 }, api_1.internal.crm.emailCronDispatch.dispatchEmailSync);
+exports.default = crons;

package/dist/convex/integrations.js

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.remove = exports.disconnect = exports.upsert = exports.isConnected = exports.listActive = exports.list = void 0;
+const server_1 = require("./_generated/server");
+const values_1 = require("convex/values");
+/**
+ * List all integrations for the current workspace
+ * Uses user.activeWorkspaceId from Convex
+ */
+exports.list = (0, server_1.query)({
+    args: {},
+    handler: async (ctx) => {
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            return [];
+        const user = await ctx.db
+            .query('users')
+            .withIndex('by_clerk_id', (q) => q.eq('clerkId', identity.subject))
+            .first();
+        const workspaceId = user?.activeWorkspaceId;
+        if (!workspaceId)
+            return [];
+        return await ctx.db
+            .query('integrations')
+            .withIndex('by_workspace', (q) => q.eq('workspaceId', workspaceId))
+            .collect();
+    },
+});
+/**
+ * Get active integrations for the current workspace
+ * Used by chat route to know which tools to initialize
+ */
+exports.listActive = (0, server_1.query)({
+    args: {},
+    handler: async (ctx) => {
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            return [];
+        const user = await ctx.db
+            .query('users')
+            .withIndex('by_clerk_id', (q) => q.eq('clerkId', identity.subject))
+            .first();
+        const workspaceId = user?.activeWorkspaceId;
+        if (!workspaceId)
+            return [];
+        const integrations = await ctx.db
+            .query('integrations')
+            .withIndex('by_workspace_status', (q) => q.eq('workspaceId', workspaceId).eq('status', 'active'))
+            .collect();
+        return integrations.map((i) => ({
+            toolkitSlug: i.toolkitSlug,
+            connectionId: i.connectionId,
+        }));
+    },
+});
+/**
+ * Check if a specific toolkit is connected
+ */
+exports.isConnected = (0, server_1.query)({
+    args: { toolkitSlug: values_1.v.string() },
+    handler: async (ctx, { toolkitSlug }) => {
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            return false;
+        const user = await ctx.db
+            .query('users')
+            .withIndex('by_clerk_id', (q) => q.eq('clerkId', identity.subject))
+            .first();
+        const workspaceId = user?.activeWorkspaceId;
+        if (!workspaceId)
+            return false;
+        const integration = await ctx.db
+            .query('integrations')
+            .withIndex('by_workspace_toolkit', (q) => q
+            .eq('workspaceId', workspaceId)
+            .eq('toolkitSlug', toolkitSlug.toUpperCase()))
+            .first();
+        return integration?.status === 'active';
+    },
+});
+/**
+ * Add or update an integration after OAuth success
+ */
+exports.upsert = (0, server_1.mutation)({
+    args: {
+        toolkitSlug: values_1.v.string(),
+        connectionId: values_1.v.string(),
+    },
+    handler: async (ctx, { toolkitSlug, connectionId }) => {
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            throw new Error('Not authenticated');
+        const user = await ctx.db
+            .query('users')
+            .withIndex('by_clerk_id', (q) => q.eq('clerkId', identity.subject))
+            .first();
+        if (!user)
+            throw new Error('User not found');
+        const workspaceId = user.activeWorkspaceId;
+        if (!workspaceId)
+            throw new Error('No active workspace');
+        const normalizedSlug = toolkitSlug.toUpperCase();
+        // Check for existing integration
+        const existing = await ctx.db
+            .query('integrations')
+            .withIndex('by_workspace_toolkit', (q) => q.eq('workspaceId', workspaceId).eq('toolkitSlug', normalizedSlug))
+            .first();
+        if (existing) {
+            // Update existing
+            await ctx.db.patch(existing._id, {
+                connectionId,
+                status: 'active',
+                connectedAt: Date.now(),
+                connectedBy: user._id,
+            });
+            return existing._id;
+        }
+        // Create new
+        return await ctx.db.insert('integrations', {
+            workspaceId,
+            toolkitSlug: normalizedSlug,
+            connectionId,
+            status: 'active',
+            connectedAt: Date.now(),
+            connectedBy: user._id,
+        });
+    },
+});
+/**
+ * Disconnect an integration (soft delete)
+ */
+exports.disconnect = (0, server_1.mutation)({
+    args: { toolkitSlug: values_1.v.string() },
+    handler: async (ctx, { toolkitSlug }) => {
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            throw new Error('Not authenticated');
+        const user = await ctx.db
+            .query('users')
+            .withIndex('by_clerk_id', (q) => q.eq('clerkId', identity.subject))
+            .first();
+        const workspaceId = user?.activeWorkspaceId;
+        if (!workspaceId)
+            throw new Error('No active workspace');
+        const normalizedSlug = toolkitSlug.toUpperCase();
+        const integration = await ctx.db
+            .query('integrations')
+            .withIndex('by_workspace_toolkit', (q) => q.eq('workspaceId', workspaceId).eq('toolkitSlug', normalizedSlug))
+            .first();
+        if (!integration) {
+            throw new Error('Integration not found');
+        }
+        // Soft delete - mark as disconnected
+        await ctx.db.patch(integration._id, {
+            status: 'disconnected',
+        });
+        return { success: true };
+    },
+});
+/**
+ * Remove an integration completely
+ */
+exports.remove = (0, server_1.mutation)({
+    args: { id: values_1.v.id('integrations') },
+    handler: async (ctx, { id }) => {
+        const identity = await ctx.auth.getUserIdentity();
+        if (!identity)
+            throw new Error('Not authenticated');
+        const user = await ctx.db
+            .query('users')
+            .withIndex('by_clerk_id', (q) => q.eq('clerkId', identity.subject))
+            .first();
+        const workspaceId = user?.activeWorkspaceId;
+        if (!workspaceId)
+            throw new Error('No active workspace');
+        const integration = await ctx.db.get(id);
+        if (!integration || integration.workspaceId !== workspaceId) {
+            throw new Error('Integration not found');
+        }
+        await ctx.db.delete(id);
+        return { success: true };
+    },
+});

package/dist/convex/lib/auditLog.js

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * convex/lib/auditLog.ts
+ *
+ * withAuditLog<T> — wraps every CRM mutation to capture a compliance trace.
+ * Captures before/after field diffs, actorId, actorType, timestamp.
+ * Inserts into audit_log table. 7-year retention. OQ-1/OQ-4 doctrine.
+ *
+ * Ref: vantage-crm-spec-2026-05-20.md §5 D-006
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.diffRecords = diffRecords;
+exports.withAuditLog = withAuditLog;
+exports.withAuditLogDiff = withAuditLogDiff;
+// ---------------------------------------------------------------------------
+// Core helper — diff two plain objects to produce fieldChanges array.
+// Only captures top-level scalar fields (no deep nesting per audit_log schema).
+// ---------------------------------------------------------------------------
+function diffRecords(before, after) {
+    const changes = [];
+    // Skip system fields that are always updated
+    const skipFields = new Set(['updatedAt', '_creationTime']);
+    const allKeys = new Set([...Object.keys(before), ...Object.keys(after)]);
+    for (const key of allKeys) {
+        if (skipFields.has(key))
+            continue;
+        const oldRaw = before[key];
+        const newRaw = after[key];
+        // Only capture top-level scalars
+        if ((typeof oldRaw === 'string' ||
+            typeof oldRaw === 'number' ||
+            typeof oldRaw === 'boolean' ||
+            oldRaw === null ||
+            oldRaw === undefined) &&
+            (typeof newRaw === 'string' ||
+                typeof newRaw === 'number' ||
+                typeof newRaw === 'boolean' ||
+                newRaw === null ||
+                newRaw === undefined)) {
+            const oldVal = oldRaw === undefined ? null : oldRaw;
+            const newVal = newRaw === undefined ? null : newRaw;
+            if (oldVal !== newVal) {
+                changes.push({ fieldName: key, oldValue: oldVal, newValue: newVal });
+            }
+        }
+    }
+    return changes;
+}
+// ---------------------------------------------------------------------------
+// withAuditLog<T> — the primary wrapper for all CRM mutations.
+//
+// Usage:
+//   return withAuditLog(ctx, {
+//     workspaceId, actorId, actorType, entityType, entityId: contactId, action: 'create',
+//   }, async () => {
+//     return await ctx.db.insert('contacts', { ... });
+//   });
+// ---------------------------------------------------------------------------
+async function withAuditLog(ctx, auditCtx, fn) {
+    const result = await fn();
+    await ctx.db.insert('audit_log', {
+        workspaceId: auditCtx.workspaceId,
+        actorId: auditCtx.actorId,
+        actorType: auditCtx.actorType,
+        entityType: auditCtx.entityType,
+        entityId: auditCtx.entityId,
+        action: auditCtx.action,
+        fieldChanges: auditCtx.fieldChanges,
+        metadata: auditCtx.metadata,
+        ip: auditCtx.ip,
+        userAgent: auditCtx.userAgent,
+        timestamp: Date.now(),
+    });
+    return result;
+}
+// ---------------------------------------------------------------------------
+// withAuditLogDiff — captures before/after diff automatically.
+// Use for update mutations where you have the record before the patch.
+// ---------------------------------------------------------------------------
+async function withAuditLogDiff(ctx, auditCtx, beforeRecord, fn) {
+    const result = await fn();
+    // Fetch record after mutation to compute diff
+    let afterRecord = {};
+    try {
+        // entityId is a Convex Id string — retrieve the updated record
+        const updated = await ctx.db.get(auditCtx.entityId);
+        if (updated) {
+            afterRecord = updated;
+        }
+    }
+    catch {
+        // If we can't fetch (e.g. deleted), leave afterRecord empty
+    }
+    const fieldChanges = diffRecords(beforeRecord, afterRecord);
+    await ctx.db.insert('audit_log', {
+        workspaceId: auditCtx.workspaceId,
+        actorId: auditCtx.actorId,
+        actorType: auditCtx.actorType,
+        entityType: auditCtx.entityType,
+        entityId: auditCtx.entityId,
+        action: auditCtx.action,
+        fieldChanges: fieldChanges.length > 0 ? fieldChanges : undefined,
+        metadata: auditCtx.metadata,
+        ip: auditCtx.ip,
+        userAgent: auditCtx.userAgent,
+        timestamp: Date.now(),
+    });
+    return result;
+}