@vantageos/vantage-crm-mcp 0.1.0

package/dist/convex/crm/companies.js

@@ -0,0 +1,323 @@
+"use strict";
+/**
+ * convex/crm/companies.ts
+ *
+ * V0.1.0 — Extended from T3 stub.
+ * Functions: createCompany, updateCompany, getCompany, listCompanies,
+ *            archiveCompany, restoreCompany, deleteCompany (admin only).
+ * Integrates: customFields (D-004) + isArchived/archivedAt (OQ-4).
+ * Every mutation wrapped in audit log insertion.
+ *
+ * Ref: vantage-crm-spec-2026-05-20.md §2 + §5
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.search = exports.deleteCompany = exports.restoreCompany = exports.remove = exports.archiveCompany = exports.list = exports.listCompanies = exports.update = exports.updateCompany = exports.get = exports.getCompany = exports.create = exports.createCompany = void 0;
+const server_1 = require("../_generated/server");
+const values_1 = require("convex/values");
+const workspace_1 = require("../lib/workspace");
+const auditLog_1 = require("../lib/auditLog");
+const rbac_1 = require("../lib/rbac");
+const _helpers_1 = require("./_helpers");
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+const sizeValidator = values_1.v.optional(values_1.v.union(values_1.v.literal('1-10'), values_1.v.literal('11-50'), values_1.v.literal('51-200'), values_1.v.literal('201-1000'), values_1.v.literal('1000+')));
+// ---------------------------------------------------------------------------
+// createCompany
+// ---------------------------------------------------------------------------
+exports.createCompany = (0, server_1.mutation)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        name: values_1.v.string(),
+        domain: values_1.v.optional(values_1.v.string()),
+        website: values_1.v.optional(values_1.v.string()),
+        industry: values_1.v.optional(values_1.v.string()),
+        size: sizeValidator,
+        phone: values_1.v.optional(values_1.v.string()),
+        address: values_1.v.optional(values_1.v.string()),
+        description: values_1.v.optional(values_1.v.string()),
+        tags: values_1.v.optional(values_1.v.array(values_1.v.string())),
+        notes: values_1.v.optional(values_1.v.string()),
+        customFields: values_1.v.optional(values_1.v.record(values_1.v.string(), values_1.v.any())),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('companies'),
+    handler: async (ctx, args) => {
+        const { clerkId, canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, args.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        const searchableText = (0, _helpers_1.buildCompanySearchText)({
+            name: args.name,
+            domain: args.domain,
+            industry: args.industry,
+        });
+        const now = Date.now();
+        const companyId = await ctx.db.insert('companies', {
+            name: args.name,
+            domain: args.domain,
+            website: args.website,
+            industry: args.industry,
+            size: args.size,
+            phone: args.phone,
+            address: args.address,
+            description: args.description,
+            tags: args.tags,
+            notes: args.notes,
+            customFields: args.customFields,
+            workspaceId: args.workspaceId,
+            ownerId: clerkId,
+            searchableText,
+            createdAt: now,
+            updatedAt: now,
+        });
+        await ctx.db.insert('audit_log', {
+            workspaceId: args.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'company',
+            entityId: companyId,
+            action: 'create',
+            timestamp: Date.now(),
+        });
+        return companyId;
+    },
+});
+// Backward-compatible alias
+exports.create = exports.createCompany;
+// ---------------------------------------------------------------------------
+// getCompany / get
+// ---------------------------------------------------------------------------
+exports.getCompany = (0, server_1.query)({
+    args: {
+        companyId: values_1.v.id('companies'),
+    },
+    returns: values_1.v.union(values_1.v.null(), values_1.v.any()),
+    handler: async (ctx, args) => {
+        const company = await ctx.db.get(args.companyId);
+        if (!company)
+            return null;
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, company.workspaceId);
+        const contacts = await ctx.db
+            .query('contacts')
+            .withIndex('by_company', (q) => q.eq('companyId', args.companyId))
+            .take(1000);
+        const contactCount = contacts.filter((c) => c.isArchived !== true).length;
+        const deals = await ctx.db
+            .query('deals')
+            .withIndex('by_company', (q) => q.eq('companyId', args.companyId))
+            .take(1000);
+        const dealCount = deals.filter((d) => d.isArchived !== true).length;
+        return { ...company, contactCount, dealCount };
+    },
+});
+exports.get = exports.getCompany;
+// ---------------------------------------------------------------------------
+// updateCompany / update
+// ---------------------------------------------------------------------------
+exports.updateCompany = (0, server_1.mutation)({
+    args: {
+        companyId: values_1.v.id('companies'),
+        name: values_1.v.optional(values_1.v.string()),
+        domain: values_1.v.optional(values_1.v.string()),
+        website: values_1.v.optional(values_1.v.string()),
+        industry: values_1.v.optional(values_1.v.string()),
+        size: sizeValidator,
+        phone: values_1.v.optional(values_1.v.string()),
+        address: values_1.v.optional(values_1.v.string()),
+        description: values_1.v.optional(values_1.v.string()),
+        tags: values_1.v.optional(values_1.v.array(values_1.v.string())),
+        notes: values_1.v.optional(values_1.v.string()),
+        customFields: values_1.v.optional(values_1.v.record(values_1.v.string(), values_1.v.any())),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('companies'),
+    handler: async (ctx, args) => {
+        const company = await ctx.db.get(args.companyId);
+        if (!company)
+            throw new Error('Company not found');
+        const { canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, company.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        const { companyId, actorId: _actorId, ...updates } = args;
+        const name = updates.name ?? company.name;
+        const domain = updates.domain ?? company.domain;
+        const industry = updates.industry ?? company.industry;
+        const searchableText = (0, _helpers_1.buildCompanySearchText)({ name, domain, industry });
+        const beforeRecord = { ...company };
+        await ctx.db.patch(companyId, {
+            ...updates,
+            searchableText,
+            updatedAt: Date.now(),
+        });
+        const afterRecord = (await ctx.db.get(companyId)) ?? {};
+        const fieldChanges = (0, auditLog_1.diffRecords)(beforeRecord, afterRecord);
+        await ctx.db.insert('audit_log', {
+            workspaceId: company.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'company',
+            entityId: companyId,
+            action: 'update',
+            fieldChanges: fieldChanges.length > 0 ? fieldChanges : undefined,
+            timestamp: Date.now(),
+        });
+        return companyId;
+    },
+});
+exports.update = exports.updateCompany;
+// ---------------------------------------------------------------------------
+// listCompanies / list
+// ---------------------------------------------------------------------------
+exports.listCompanies = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        industry: values_1.v.optional(values_1.v.string()),
+        includeArchived: values_1.v.optional(values_1.v.boolean()),
+        limit: 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 limit = args.limit ?? 50;
+        const companies = await ctx.db
+            .query('companies')
+            .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+            .order('desc')
+            .take(limit + 1);
+        let filtered = args.includeArchived
+            ? companies
+            : companies.filter((c) => c.isArchived !== true);
+        if (args.industry) {
+            filtered = filtered.filter((c) => c.industry === args.industry);
+        }
+        return filtered.slice(0, limit);
+    },
+});
+exports.list = exports.listCompanies;
+// ---------------------------------------------------------------------------
+// archiveCompany (OQ-4 soft delete)
+// ---------------------------------------------------------------------------
+exports.archiveCompany = (0, server_1.mutation)({
+    args: {
+        companyId: values_1.v.id('companies'),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('companies'),
+    handler: async (ctx, args) => {
+        const company = await ctx.db.get(args.companyId);
+        if (!company)
+            throw new Error('Company not found');
+        const { canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, company.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        if (company.isArchived)
+            throw new Error('Company is already archived');
+        const now = Date.now();
+        return (0, auditLog_1.withAuditLog)(ctx, {
+            workspaceId: company.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'company',
+            entityId: args.companyId,
+            action: 'archive',
+        }, async () => {
+            await ctx.db.patch(args.companyId, {
+                isArchived: true,
+                archivedAt: now,
+                updatedAt: now,
+            });
+            return args.companyId;
+        });
+    },
+});
+// Backward-compatible alias
+exports.remove = exports.archiveCompany;
+// ---------------------------------------------------------------------------
+// restoreCompany
+// ---------------------------------------------------------------------------
+exports.restoreCompany = (0, server_1.mutation)({
+    args: {
+        companyId: values_1.v.id('companies'),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('companies'),
+    handler: async (ctx, args) => {
+        const company = await ctx.db.get(args.companyId);
+        if (!company)
+            throw new Error('Company not found');
+        const { canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, company.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        if (!company.isArchived)
+            throw new Error('Company is not archived');
+        return (0, auditLog_1.withAuditLog)(ctx, {
+            workspaceId: company.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'company',
+            entityId: args.companyId,
+            action: 'restore',
+        }, async () => {
+            await ctx.db.patch(args.companyId, {
+                isArchived: false,
+                archivedAt: undefined,
+                updatedAt: Date.now(),
+            });
+            return args.companyId;
+        });
+    },
+});
+// ---------------------------------------------------------------------------
+// deleteCompany — ADMIN SCOPE ONLY (hard delete, OQ-4: 30j grace)
+// ---------------------------------------------------------------------------
+exports.deleteCompany = (0, server_1.mutation)({
+    args: {
+        companyId: values_1.v.id('companies'),
+    },
+    returns: values_1.v.id('companies'),
+    handler: async (ctx, args) => {
+        const company = await ctx.db.get(args.companyId);
+        if (!company)
+            throw new Error('Company not found');
+        const { role, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, company.workspaceId);
+        await (0, rbac_1.assertAdminScope)(ctx, role);
+        if (!company.isArchived) {
+            throw new Error('Company must be archived before hard delete');
+        }
+        const archivedAt = company.archivedAt ?? 0;
+        const gracePeriodMs = 30 * 24 * 60 * 60 * 1000;
+        if (Date.now() - archivedAt < gracePeriodMs) {
+            const daysLeft = Math.ceil((gracePeriodMs - (Date.now() - archivedAt)) / (24 * 60 * 60 * 1000));
+            throw new Error(`Company cannot be hard deleted yet. ${daysLeft} day(s) remaining in grace period.`);
+        }
+        await ctx.db.insert('audit_log', {
+            workspaceId: company.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'company',
+            entityId: args.companyId,
+            action: 'delete',
+            timestamp: Date.now(),
+        });
+        await ctx.db.delete(args.companyId);
+        return args.companyId;
+    },
+});
+// ---------------------------------------------------------------------------
+// search — preserved from T3
+// ---------------------------------------------------------------------------
+exports.search = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        query: values_1.v.string(),
+    },
+    returns: values_1.v.array(values_1.v.any()),
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const results = await ctx.db
+            .query('companies')
+            .withSearchIndex('search_companies', (q) => q.search('searchableText', args.query).eq('workspaceId', args.workspaceId))
+            .take(50);
+        return results.filter((c) => c.isArchived !== true);
+    },
+});

package/dist/convex/crm/contacts.js

@@ -0,0 +1,346 @@
+"use strict";
+/**
+ * convex/crm/contacts.ts
+ *
+ * V0.1.0 — Extended from T3 stub.
+ * Functions: createContact, updateContact, getContact, listContacts,
+ *            archiveContact, restoreContact, deleteContact (admin only).
+ * Integrates: vpProfileId (OQ-3) + customFields (D-004) + isArchived/archivedAt (OQ-4).
+ * Every mutation wrapped in withAuditLog. Auth via assertWorkspaceAccess + requireScope.
+ *
+ * Ref: vantage-crm-spec-2026-05-20.md §2 + §5 OQ-3/OQ-4
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.search = exports.deleteContact = exports.restoreContact = exports.remove = exports.archiveContact = exports.list = exports.listContacts = exports.update = exports.updateContact = exports.get = exports.getContact = exports.create = exports.createContact = void 0;
+const server_1 = require("../_generated/server");
+const values_1 = require("convex/values");
+const workspace_1 = require("../lib/workspace");
+const auditLog_1 = require("../lib/auditLog");
+const rbac_1 = require("../lib/rbac");
+const _helpers_1 = require("./_helpers");
+// ---------------------------------------------------------------------------
+// Validators
+// ---------------------------------------------------------------------------
+const contactTypeValidator = values_1.v.union(values_1.v.literal('lead'), values_1.v.literal('prospect'), values_1.v.literal('client'), values_1.v.literal('partner'), values_1.v.literal('other'));
+// ---------------------------------------------------------------------------
+// createContact
+// ---------------------------------------------------------------------------
+exports.createContact = (0, server_1.mutation)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        firstName: values_1.v.string(),
+        lastName: values_1.v.string(),
+        email: values_1.v.optional(values_1.v.string()),
+        phone: values_1.v.optional(values_1.v.string()),
+        companyId: values_1.v.optional(values_1.v.id('companies')),
+        type: contactTypeValidator,
+        source: values_1.v.optional(values_1.v.string()),
+        tags: values_1.v.optional(values_1.v.array(values_1.v.string())),
+        notes: values_1.v.optional(values_1.v.string()),
+        jobTitle: values_1.v.optional(values_1.v.string()),
+        linkedinUrl: values_1.v.optional(values_1.v.string()),
+        address: values_1.v.optional(values_1.v.string()),
+        vpProfileId: values_1.v.optional(values_1.v.string()),
+        customFields: values_1.v.optional(values_1.v.record(values_1.v.string(), values_1.v.any())),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('contacts'),
+    handler: async (ctx, args) => {
+        const { clerkId, canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, args.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        let companyName;
+        if (args.companyId) {
+            const company = await ctx.db.get(args.companyId);
+            companyName = company?.name;
+        }
+        const searchableText = (0, _helpers_1.buildContactSearchText)({ firstName: args.firstName, lastName: args.lastName, email: args.email }, companyName);
+        const now = Date.now();
+        const contactId = await ctx.db.insert('contacts', {
+            firstName: args.firstName,
+            lastName: args.lastName,
+            email: args.email,
+            phone: args.phone,
+            companyId: args.companyId,
+            type: args.type,
+            source: args.source,
+            tags: args.tags,
+            notes: args.notes,
+            jobTitle: args.jobTitle,
+            linkedinUrl: args.linkedinUrl,
+            address: args.address,
+            vpProfileId: args.vpProfileId,
+            customFields: args.customFields,
+            workspaceId: args.workspaceId,
+            ownerId: clerkId,
+            searchableText,
+            createdAt: now,
+            updatedAt: now,
+        });
+        await ctx.db.insert('audit_log', {
+            workspaceId: args.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'contact',
+            entityId: contactId,
+            action: 'create',
+            timestamp: Date.now(),
+        });
+        return contactId;
+    },
+});
+// Backward-compatible alias for T3 API consumers
+exports.create = exports.createContact;
+// ---------------------------------------------------------------------------
+// getContact / get
+// ---------------------------------------------------------------------------
+exports.getContact = (0, server_1.query)({
+    args: {
+        contactId: values_1.v.id('contacts'),
+    },
+    returns: values_1.v.union(values_1.v.null(), values_1.v.any()),
+    handler: async (ctx, args) => {
+        const contact = await ctx.db.get(args.contactId);
+        if (!contact)
+            return null;
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, contact.workspaceId);
+        let company = null;
+        if (contact.companyId) {
+            company = await ctx.db.get(contact.companyId);
+        }
+        return { ...contact, company };
+    },
+});
+exports.get = exports.getContact;
+// ---------------------------------------------------------------------------
+// updateContact / update
+// ---------------------------------------------------------------------------
+exports.updateContact = (0, server_1.mutation)({
+    args: {
+        contactId: values_1.v.id('contacts'),
+        firstName: values_1.v.optional(values_1.v.string()),
+        lastName: values_1.v.optional(values_1.v.string()),
+        email: values_1.v.optional(values_1.v.string()),
+        phone: values_1.v.optional(values_1.v.string()),
+        companyId: values_1.v.optional(values_1.v.id('companies')),
+        type: values_1.v.optional(contactTypeValidator),
+        source: values_1.v.optional(values_1.v.string()),
+        tags: values_1.v.optional(values_1.v.array(values_1.v.string())),
+        notes: values_1.v.optional(values_1.v.string()),
+        jobTitle: values_1.v.optional(values_1.v.string()),
+        linkedinUrl: values_1.v.optional(values_1.v.string()),
+        address: values_1.v.optional(values_1.v.string()),
+        avatarUrl: values_1.v.optional(values_1.v.string()),
+        lastContactedAt: values_1.v.optional(values_1.v.number()),
+        leadScore: values_1.v.optional(values_1.v.number()),
+        vpProfileId: values_1.v.optional(values_1.v.string()),
+        customFields: values_1.v.optional(values_1.v.record(values_1.v.string(), values_1.v.any())),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('contacts'),
+    handler: async (ctx, args) => {
+        const contact = await ctx.db.get(args.contactId);
+        if (!contact)
+            throw new Error('Contact not found');
+        const { canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, contact.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        const { contactId, actorId: _actorId, ...updates } = args;
+        const firstName = updates.firstName ?? contact.firstName;
+        const lastName = updates.lastName ?? contact.lastName;
+        const email = updates.email ?? contact.email;
+        let companyName;
+        const companyId = updates.companyId ?? contact.companyId;
+        if (companyId) {
+            const company = await ctx.db.get(companyId);
+            companyName = company?.name;
+        }
+        const searchableText = (0, _helpers_1.buildContactSearchText)({ firstName, lastName, email }, companyName);
+        const beforeRecord = { ...contact };
+        await ctx.db.patch(contactId, {
+            ...updates,
+            searchableText,
+            updatedAt: Date.now(),
+        });
+        // Fetch updated record for diff
+        const afterRecord = (await ctx.db.get(contactId)) ?? {};
+        const fieldChanges = (0, auditLog_1.diffRecords)(beforeRecord, afterRecord);
+        await ctx.db.insert('audit_log', {
+            workspaceId: contact.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'contact',
+            entityId: contactId,
+            action: 'update',
+            fieldChanges: fieldChanges.length > 0 ? fieldChanges : undefined,
+            timestamp: Date.now(),
+        });
+        return contactId;
+    },
+});
+exports.update = exports.updateContact;
+// ---------------------------------------------------------------------------
+// listContacts / list
+// ---------------------------------------------------------------------------
+exports.listContacts = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        type: values_1.v.optional(contactTypeValidator),
+        companyId: values_1.v.optional(values_1.v.id('companies')),
+        includeArchived: values_1.v.optional(values_1.v.boolean()),
+        limit: 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 limit = args.limit ?? 50;
+        let contacts;
+        if (args.type) {
+            contacts = await ctx.db
+                .query('contacts')
+                .withIndex('by_workspace_type', (q) => q.eq('workspaceId', args.workspaceId).eq('type', args.type))
+                .order('desc')
+                .take(1000);
+        }
+        else {
+            contacts = await ctx.db
+                .query('contacts')
+                .withIndex('by_workspace', (q) => q.eq('workspaceId', args.workspaceId))
+                .order('desc')
+                .take(1000);
+        }
+        let filtered = args.includeArchived ? contacts : contacts.filter((c) => c.isArchived !== true);
+        if (args.companyId) {
+            filtered = filtered.filter((c) => c.companyId === args.companyId);
+        }
+        return filtered.slice(0, limit);
+    },
+});
+exports.list = exports.listContacts;
+// ---------------------------------------------------------------------------
+// archiveContact (OQ-4 soft delete)
+// ---------------------------------------------------------------------------
+exports.archiveContact = (0, server_1.mutation)({
+    args: {
+        contactId: values_1.v.id('contacts'),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('contacts'),
+    handler: async (ctx, args) => {
+        const contact = await ctx.db.get(args.contactId);
+        if (!contact)
+            throw new Error('Contact not found');
+        const { canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, contact.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        if (contact.isArchived)
+            throw new Error('Contact is already archived');
+        const now = Date.now();
+        return (0, auditLog_1.withAuditLog)(ctx, {
+            workspaceId: contact.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'contact',
+            entityId: args.contactId,
+            action: 'archive',
+        }, async () => {
+            await ctx.db.patch(args.contactId, {
+                isArchived: true,
+                archivedAt: now,
+                updatedAt: now,
+            });
+            return args.contactId;
+        });
+    },
+});
+// Backward-compatible alias (T3 remove was a soft-delete)
+exports.remove = exports.archiveContact;
+// ---------------------------------------------------------------------------
+// restoreContact (OQ-4 reverse soft delete)
+// ---------------------------------------------------------------------------
+exports.restoreContact = (0, server_1.mutation)({
+    args: {
+        contactId: values_1.v.id('contacts'),
+        actorId: values_1.v.optional(values_1.v.string()),
+    },
+    returns: values_1.v.id('contacts'),
+    handler: async (ctx, args) => {
+        const contact = await ctx.db.get(args.contactId);
+        if (!contact)
+            throw new Error('Contact not found');
+        const { canWrite, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, contact.workspaceId, args.actorId);
+        if (!canWrite)
+            throw new Error('Insufficient permissions');
+        if (!contact.isArchived)
+            throw new Error('Contact is not archived');
+        return (0, auditLog_1.withAuditLog)(ctx, {
+            workspaceId: contact.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'contact',
+            entityId: args.contactId,
+            action: 'restore',
+        }, async () => {
+            await ctx.db.patch(args.contactId, {
+                isArchived: false,
+                archivedAt: undefined,
+                updatedAt: Date.now(),
+            });
+            return args.contactId;
+        });
+    },
+});
+// ---------------------------------------------------------------------------
+// deleteContact — ADMIN SCOPE ONLY (hard delete, OQ-4: after 30j grace)
+// ---------------------------------------------------------------------------
+exports.deleteContact = (0, server_1.mutation)({
+    args: {
+        contactId: values_1.v.id('contacts'),
+    },
+    returns: values_1.v.id('contacts'),
+    handler: async (ctx, args) => {
+        const contact = await ctx.db.get(args.contactId);
+        if (!contact)
+            throw new Error('Contact not found');
+        const { role, actor } = await (0, workspace_1.assertWorkspaceAccess)(ctx, contact.workspaceId);
+        await (0, rbac_1.assertAdminScope)(ctx, role);
+        if (!contact.isArchived) {
+            throw new Error('Contact must be archived before hard delete');
+        }
+        const archivedAt = contact.archivedAt ?? 0;
+        const gracePeriodMs = 30 * 24 * 60 * 60 * 1000;
+        if (Date.now() - archivedAt < gracePeriodMs) {
+            const daysLeft = Math.ceil((gracePeriodMs - (Date.now() - archivedAt)) / (24 * 60 * 60 * 1000));
+            throw new Error(`Contact cannot be hard deleted yet. ${daysLeft} day(s) remaining in 30-day grace period.`);
+        }
+        await ctx.db.insert('audit_log', {
+            workspaceId: contact.workspaceId,
+            actorId: actor.actorId,
+            actorType: actor.auditActorType,
+            entityType: 'contact',
+            entityId: args.contactId,
+            action: 'delete',
+            timestamp: Date.now(),
+        });
+        await ctx.db.delete(args.contactId);
+        return args.contactId;
+    },
+});
+// ---------------------------------------------------------------------------
+// search — preserved from T3
+// ---------------------------------------------------------------------------
+exports.search = (0, server_1.query)({
+    args: {
+        workspaceId: values_1.v.id('workspaces'),
+        query: values_1.v.string(),
+    },
+    returns: values_1.v.array(values_1.v.any()),
+    handler: async (ctx, args) => {
+        await (0, workspace_1.validateWorkspaceAccess)(ctx, args.workspaceId);
+        const results = await ctx.db
+            .query('contacts')
+            .withSearchIndex('search_contacts', (q) => q.search('searchableText', args.query).eq('workspaceId', args.workspaceId))
+            .take(50);
+        return results.filter((c) => c.isArchived !== true);
+    },
+});