import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; import { getRlsExecutionContext, runWithRlsContext, runWithRlsTransaction } from "@hivegrid/db/rls-context.server"; import { buildLeadConversionEventType, LeadAlreadyConvertedError, LeadNotFoundError } from "./convertLead.server"; import { TENANT_PENDING_OWNER_REASON } from "~/domain/tenant-bootstrap/tenantBootstrap.constants"; const capabilityMocks = vi.hoisted(() => ({ convertSelfServiceMarketingLeadCapability: vi.fn() })); const ownerInvitationMocks = vi.hoisted(() => ({ issueReservedOwnerInvitationWithTx: vi.fn() })); vi.mock("~/utils/db.server", () => { return { db: { $transaction: vi.fn() } }; }); vi.mock("@hivegrid/db/outbox", () => { return { publishOutboxEvent: vi.fn(), }; }); vi.mock("@hivegrid/db/pretenant-security.server", () => ({ convertSelfServiceMarketingLeadCapability: (...args: unknown[]) => capabilityMocks.convertSelfServiceMarketingLeadCapability(...args), })); vi.mock("~/domain/tenant-bootstrap/tenantBootstrap.constants", () => ({ TENANT_PENDING_OWNER_REASON: "pending_owner", })); vi.mock("~/domain/tenant-bootstrap/ownerInvitationIssuance.server", () => ({ issueReservedOwnerInvitationWithTx: ownerInvitationMocks.issueReservedOwnerInvitationWithTx, })); const OWNER_INVITATION_TOKEN = "o".repeat(43); const OWNER_INVITATION = { issuanceKey: "lead:lead_1", email: "test@example.com", firstName: "Test", lastName: "User", fromUserId: null, token: OWNER_INVITATION_TOKEN, mail: { subject: "Invitation", html: `https://app.example.test/invitation/${OWNER_INVITATION_TOKEN}` }, }; describe("buildLeadConversionEventType", () => { it("returns convertedtotrial for trial status", () => { expect(buildLeadConversionEventType("trial")).toBe("marketing.lead.convertedtotrial"); }); it("returns convertedtocustomer for customer status", () => { expect(buildLeadConversionEventType("customer")).toBe("marketing.lead.convertedtocustomer"); }); }); describe("convertLeadToTenant", () => { let dbMock: any; let publishMock: any; let convertLeadToTenant: typeof import("./convertLead.server").convertLeadToTenant; beforeEach(async () => { vi.resetModules(); dbMock = (await import("~/utils/db.server")).db as any; publishMock = (await import("@hivegrid/db/outbox")).publishOutboxEvent as any; convertLeadToTenant = (await import("./convertLead.server")).convertLeadToTenant; ownerInvitationMocks.issueReservedOwnerInvitationWithTx.mockResolvedValue({ invitationId: "invite_owner", replayed: false }); }); afterEach(() => { vi.clearAllMocks(); }); function buildTx(leadOverrides: Record = {}) { const tx: any = { $executeRaw: vi.fn().mockResolvedValue(1), lead: { findUnique: vi.fn().mockResolvedValue({ id: "lead_1", email: "test@example.com", firstName: "Test", lastName: "User", company: "Acme", source: "landing-pro", utmSource: "google", utmMedium: "cpc", utmCampaign: "q2-launch", utmTerm: null, utmContent: null, gclid: null, fbclid: null, referrer: null, landingPage: "/pricing", firstSeenAt: new Date("2026-05-10T00:00:00Z"), status: "new", convertedToTenantId: null, ...leadOverrides, }), update: vi.fn().mockResolvedValue({}), }, tenant: { create: vi.fn().mockResolvedValue({ id: "tenant_1" }), }, leadEvent: { create: vi.fn().mockResolvedValue({}), }, tenantAcquisition: { create: vi.fn().mockResolvedValue({}), upsert: vi.fn().mockResolvedValue({}), }, }; return tx; } it("happy-path creates tenant, updates lead, inserts acquisition, publishes outbox", async () => { const tx = buildTx(); dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); publishMock.mockResolvedValue({ id: "outbox_1" }); const result = await convertLeadToTenant({ leadId: "lead_1", ownerInvitation: OWNER_INVITATION, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }); expect(result.tenantId).toBe("tenant_1"); expect(result.status).toBe("trial"); expect(result.alreadyConverted).toBe(false); expect(result.outboxEventId).toBe("outbox_1"); expect(tx.$executeRaw).toHaveBeenCalledOnce(); expect(String(tx.$executeRaw.mock.calls[0]?.[0])).toContain("pg_advisory_xact_lock"); expect(tx.tenant.create).toHaveBeenCalledOnce(); expect(ownerInvitationMocks.issueReservedOwnerInvitationWithTx).toHaveBeenCalledWith(tx, { tenantId: "tenant_1", ...OWNER_INVITATION, }); expect(tx.lead.update).toHaveBeenCalledWith( expect.objectContaining({ where: { id: "lead_1" }, data: expect.objectContaining({ status: "trial", convertedToTenantId: "tenant_1" }), }) ); expect(tx.leadEvent.create).toHaveBeenCalledWith(expect.objectContaining({ data: expect.objectContaining({ type: "converted" }) })); expect(tx.tenantAcquisition.create).toHaveBeenCalledWith( expect.objectContaining({ data: expect.objectContaining({ tenantId: "tenant_1", leadId: "lead_1", utmSource: "google", utmCampaign: "q2-launch", }), }) ); expect(publishMock).toHaveBeenCalledWith( tx, expect.objectContaining({ type: "marketing.lead.convertedtotrial", tenantId: "tenant_1", dispatchKey: "lead-convert:lead_1", }) ); expect(JSON.stringify(publishMock.mock.calls)).not.toContain(OWNER_INVITATION_TOKEN); }); it("publishes customer event when targetStatus=customer", async () => { const tx = buildTx(); dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); publishMock.mockResolvedValue({ id: "outbox_2" }); await convertLeadToTenant({ leadId: "lead_1", targetStatus: "customer", ownerInvitation: OWNER_INVITATION, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }); expect(publishMock).toHaveBeenCalledWith(tx, expect.objectContaining({ type: "marketing.lead.convertedtocustomer" })); }); it("propagates owner-mail issuance failure before mutating the lead or publishing the business event", async () => { const tx = buildTx(); dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); ownerInvitationMocks.issueReservedOwnerInvitationWithTx.mockRejectedValueOnce(new Error("mail outbox unavailable")); await expect( convertLeadToTenant({ leadId: "lead_1", ownerInvitation: OWNER_INVITATION, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }) ).rejects.toThrow("mail outbox unavailable"); expect(tx.lead.update).not.toHaveBeenCalled(); expect(tx.leadEvent.create).not.toHaveBeenCalled(); expect(tx.tenantAcquisition.create).not.toHaveBeenCalled(); expect(publishMock).not.toHaveBeenCalled(); }); it("returns alreadyConverted=true without re-creating tenant when lead already converted", async () => { const tx = buildTx({ convertedToTenantId: "tenant_existing" }); dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); const result = await convertLeadToTenant({ leadId: "lead_1", ownerInvitation: OWNER_INVITATION, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }); expect(result.alreadyConverted).toBe(true); expect(result.tenantId).toBe("tenant_existing"); expect(tx.tenant.create).not.toHaveBeenCalled(); expect(publishMock).not.toHaveBeenCalled(); }); it("rejects changed owner identity before an already-converted replay can disclose the tenant id", async () => { const tx = buildTx({ convertedToTenantId: "tenant_existing" }); dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); await expect( convertLeadToTenant({ leadId: "lead_1", ownerInvitation: { ...OWNER_INVITATION, email: "attacker@example.com" }, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }) ).rejects.toMatchObject({ name: "LeadOwnerInvitationMismatchError" }); expect(tx.tenant.create).not.toHaveBeenCalled(); expect(ownerInvitationMocks.issueReservedOwnerInvitationWithTx).not.toHaveBeenCalled(); expect(publishMock).not.toHaveBeenCalled(); }); it.each([ { firstName: null, lastName: "User" }, { firstName: "Test", lastName: " " }, ])("rejects an incomplete lead owner identity before creating the tenant", async (leadNames) => { const tx = buildTx(leadNames); dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); await expect( convertLeadToTenant({ leadId: "lead_1", ownerInvitation: { ...OWNER_INVITATION, firstName: leadNames.firstName ?? "", lastName: leadNames.lastName, }, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }) ).rejects.toMatchObject({ name: "LeadOwnerInvitationMismatchError" }); expect(tx.tenant.create).not.toHaveBeenCalled(); expect(ownerInvitationMocks.issueReservedOwnerInvitationWithTx).not.toHaveBeenCalled(); expect(tx.lead.update).not.toHaveBeenCalled(); expect(publishMock).not.toHaveBeenCalled(); }); it("serializes concurrent conversions so only one ownerless tenant is created", async () => { let convertedToTenantId: string | null = null; let lockTail = Promise.resolve(); const transactions: any[] = []; dbMock.$transaction.mockImplementation(async (fn: (tx: any) => Promise) => { const tx = buildTx(); let releaseLock: (() => void) | undefined; tx.$executeRaw.mockImplementationOnce(async () => { const previous = lockTail; lockTail = new Promise((resolve) => { releaseLock = resolve; }); await previous; return 1; }); tx.lead.findUnique.mockImplementation(async () => ({ id: "lead_1", email: "test@example.com", firstName: "Test", lastName: "User", company: "Acme", source: "landing-pro", utmSource: null, utmMedium: null, utmCampaign: null, utmTerm: null, utmContent: null, gclid: null, fbclid: null, referrer: null, landingPage: null, firstSeenAt: new Date("2026-05-10T00:00:00Z"), status: "new", convertedToTenantId, })); tx.tenant.create.mockImplementation(async ({ data }: { data: { id: string } }) => ({ id: data.id })); tx.lead.update.mockImplementation(async ({ data }: { data: { convertedToTenantId: string } }) => { convertedToTenantId = data.convertedToTenantId; return {}; }); transactions.push(tx); try { return await fn(tx); } finally { releaseLock?.(); } }); publishMock.mockResolvedValue({ id: "outbox_concurrent" }); const input = { leadId: "lead_1", ownerInvitation: OWNER_INVITATION, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, } as const; const [first, second] = await Promise.all([convertLeadToTenant(input), convertLeadToTenant(input)]); expect([first.alreadyConverted, second.alreadyConverted].sort()).toEqual([false, true]); expect(first.tenantId).toBe(second.tenantId); expect(transactions.reduce((count, tx) => count + tx.tenant.create.mock.calls.length, 0)).toBe(1); expect(transactions.every((tx) => tx.$executeRaw.mock.calls.length === 1)).toBe(true); }); it("throws LeadNotFoundError when lead missing", async () => { const tx = buildTx(); tx.lead.findUnique.mockResolvedValue(null); dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); await expect( convertLeadToTenant({ leadId: "lead_unknown", ownerInvitation: { ...OWNER_INVITATION, issuanceKey: "lead:lead_unknown" }, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }) ).rejects.toMatchObject({ name: "LeadNotFoundError" }); expect(LeadNotFoundError.name).toBe("LeadNotFoundError"); }); it("admin-override path stamps conversionPath=admin-override + actorId on LeadEvent", async () => { const tx = buildTx(); let transactionContext: ReturnType; dbMock.$transaction.mockImplementation(async (fn: any) => { transactionContext = getRlsExecutionContext(); return fn(tx); }); publishMock.mockResolvedValue({ id: "outbox_3" }); await convertLeadToTenant({ leadId: "lead_1", conversionPath: "admin-override", actorId: "user_admin", ownerInvitation: { ...OWNER_INVITATION, fromUserId: "user_admin" }, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }); expect(tx.leadEvent.create).toHaveBeenCalledWith( expect.objectContaining({ data: expect.objectContaining({ actorId: "user_admin" }), }) ); expect(tx.tenantAcquisition.create).toHaveBeenCalledWith( expect.objectContaining({ data: expect.objectContaining({ conversionPath: "admin-override" }), }) ); expect(transactionContext!).toMatchObject({ tenantId: expect.any(String), userId: "user_admin" }); expect(tx.tenant.create).toHaveBeenCalledWith( expect.objectContaining({ data: expect.objectContaining({ id: transactionContext!.tenantId, active: false, deactivatedReason: TENANT_PENDING_OWNER_REASON, }), }) ); expect(getRlsExecutionContext()).toBeNull(); }); it("isolates conversion from an inherited tenant transaction for the same operator", async () => { const tx = buildTx(); const inheritedTransaction = { id: "old-transaction" }; let transactionContext: ReturnType; dbMock.$transaction.mockImplementation(async (fn: any) => { transactionContext = getRlsExecutionContext(); return fn(tx); }); publishMock.mockResolvedValue({ id: "outbox_isolated" }); await runWithRlsContext({ tenantId: "tenant-old", userId: "user_admin" }, () => runWithRlsTransaction(inheritedTransaction, () => convertLeadToTenant({ leadId: "lead_1", conversionPath: "admin-override", actorId: "user_admin", ownerInvitation: { ...OWNER_INVITATION, fromUserId: "user_admin" }, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }) ) ); expect(transactionContext!).toMatchObject({ tenantId: expect.any(String), userId: "user_admin" }); expect(transactionContext!.tenantId).not.toBe("tenant-old"); expect(transactionContext!.transaction).toBeUndefined(); expect(getRlsExecutionContext()).toBeNull(); }); it("respects LEAD_CONVERSION_ENABLED=false rollback flag", async () => { const originalEnv = process.env.LEAD_CONVERSION_ENABLED; process.env.LEAD_CONVERSION_ENABLED = "false"; try { await expect( convertLeadToTenant({ leadId: "lead_1", ownerInvitation: OWNER_INVITATION, tenant: { name: "Acme", slug: "acme", inboundAddress: "acme@inbox.local" }, }) ).rejects.toThrow(/disabled/i); } finally { if (originalEnv === undefined) delete process.env.LEAD_CONVERSION_ENABLED; else process.env.LEAD_CONVERSION_ENABLED = originalEnv; } }); }); describe("recordExistingTenantLeadConversion", () => { let dbMock: any; let publishMock: any; let recordExistingTenantLeadConversion: typeof import("./convertLead.server").recordExistingTenantLeadConversion; beforeEach(async () => { vi.resetModules(); dbMock = (await import("~/utils/db.server")).db as any; publishMock = (await import("@hivegrid/db/outbox")).publishOutboxEvent as any; recordExistingTenantLeadConversion = (await import("./convertLead.server")).recordExistingTenantLeadConversion; capabilityMocks.convertSelfServiceMarketingLeadCapability.mockReset(); }); afterEach(() => { vi.clearAllMocks(); }); function conversionSummary(overrides: Record = {}) { return { leadId: "lead_1", convertedToTenantId: "tenant_registered", alreadyConverted: false, email: "test@example.com", firstName: "Test", lastName: "User", company: "Acme", source: "landing-pro", utmSource: "google", utmMedium: "cpc", utmCampaign: "q2-launch", utmTerm: null, utmContent: null, gclid: null, fbclid: null, referrer: null, landingPage: "/pricing", firstSeenAt: "2026-05-10T00:00:00.000Z", convertedAt: "2026-05-11T00:00:00.000Z", ...overrides, }; } it("links an already-created registration tenant to the lead attribution and outbox event", async () => { const tx = {}; dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); capabilityMocks.convertSelfServiceMarketingLeadCapability.mockResolvedValue(conversionSummary()); publishMock.mockResolvedValue({ id: "outbox_4" }); const result = await recordExistingTenantLeadConversion({ leadId: "lead_1", tenantId: "tenant_registered", userId: "user_1", expectedEmail: "test@example.com", planId: "plan_pro", conversionPath: "self-service", }); expect(result).toMatchObject({ tenantId: "tenant_registered", leadId: "lead_1", alreadyConverted: false, outboxEventId: "outbox_4" }); expect(capabilityMocks.convertSelfServiceMarketingLeadCapability).toHaveBeenCalledWith( { leadId: "lead_1", tenantId: "tenant_registered", userId: "user_1", expectedEmail: "test@example.com", planId: "plan_pro", }, tx ); expect(publishMock).toHaveBeenCalledWith( tx, expect.objectContaining({ tenantId: "tenant_registered", type: "marketing.lead.convertedtotrial", dispatchKey: "lead-convert:lead_1", payload: expect.objectContaining({ leadId: "lead_1", tenantId: "tenant_registered", planId: "plan_pro" }), }) ); }); it("is idempotent when the same tenant already owns the lead conversion", async () => { const tx = {}; dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); capabilityMocks.convertSelfServiceMarketingLeadCapability.mockResolvedValue(conversionSummary({ alreadyConverted: true })); const result = await recordExistingTenantLeadConversion({ leadId: "lead_1", tenantId: "tenant_registered", userId: "user_1", expectedEmail: "test@example.com", }); expect(result.alreadyConverted).toBe(true); expect(publishMock).not.toHaveBeenCalled(); }); it("rejects a lead already converted to a different tenant", async () => { const tx = {}; dbMock.$transaction.mockImplementation(async (fn: any) => fn(tx)); capabilityMocks.convertSelfServiceMarketingLeadCapability.mockResolvedValue( conversionSummary({ convertedToTenantId: "tenant_other", alreadyConverted: true }) ); await expect( recordExistingTenantLeadConversion({ leadId: "lead_1", tenantId: "tenant_registered", userId: "user_1", expectedEmail: "test@example.com", }) ).rejects.toMatchObject({ name: "LeadAlreadyConvertedError", convertedToTenantId: "tenant_other" }); expect(LeadAlreadyConvertedError.name).toBe("LeadAlreadyConvertedError"); }); });