Files
HiveGrid-Wireframes/03 Quellen und Referenzen/hivegrid-cloud/apps/web/app/utils/leads/convertLead.test.ts
T

520 lines
19 KiB
TypeScript

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<string, unknown> = {}) {
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<unknown>) => {
const tx = buildTx();
let releaseLock: (() => void) | undefined;
tx.$executeRaw.mockImplementationOnce(async () => {
const previous = lockTail;
lockTail = new Promise<void>((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<typeof getRlsExecutionContext>;
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<typeof getRlsExecutionContext>;
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<string, unknown> = {}) {
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");
});
});