Refresh HiveGrid Cloud reference snapshot
This commit is contained in:
1 parent
5e99e14772
commit
7f88026f79
5955 files changed
+1177325
-188362
No files matched your search
+133
-154
@@ -3,20 +3,22 @@
|
||||
* Phase 05 #79).
|
||||
*
|
||||
* `convertLeadToTenant` runs inside a single Prisma `$transaction` so the
|
||||
* following five effects either all commit or all roll back together:
|
||||
* following six effects either all commit or all roll back together:
|
||||
*
|
||||
* 1. New Tenant row (via direct prisma.create — we cannot reuse the
|
||||
* higher-level `createTenant` helper because it runs outside a
|
||||
* transaction. Slug + inboundAddress allocation is delegated to the
|
||||
* pre-computed values passed in by the caller).
|
||||
* 2. Lead row update: `status` advances to `trial` (default) or
|
||||
* 2. A single pending OWNER invitation plus its transactional-mail
|
||||
* outbox row.
|
||||
* 3. Lead row update: `status` advances to `trial` (default) or
|
||||
* `customer` (when caller requests it), `convertedToTenantId` +
|
||||
* `convertedAt` populated.
|
||||
* 3. `LeadEvent` of type `converted` appended for the activity
|
||||
* 4. `LeadEvent` of type `converted` appended for the activity
|
||||
* timeline.
|
||||
* 4. `TenantAcquisition` row inserted with first-touch attribution
|
||||
* 5. `TenantAcquisition` row inserted with first-touch attribution
|
||||
* snapshot copied from the Lead.
|
||||
* 5. `OutboxEvent` published — `marketing.lead.convertedtotrial` or
|
||||
* 6. `OutboxEvent` published — `marketing.lead.convertedtotrial` or
|
||||
* `marketing.lead.convertedtocustomer` — picked up downstream by
|
||||
* the marketing-outbound worker handler to fan out webhooks (Slack,
|
||||
* Discord, Mailchimp, HubSpot, Brevo, custom).
|
||||
@@ -28,9 +30,18 @@
|
||||
* into no-ops, returning the already-created Tenant + Lead.
|
||||
*/
|
||||
|
||||
import { randomUUID } from "node:crypto";
|
||||
|
||||
import { Prisma } from "@hivegrid/db/prisma-browser";
|
||||
import { publishOutboxEvent, type OutboxPublisherTransaction } from "@hivegrid/db/outbox";
|
||||
import { convertSelfServiceMarketingLeadCapability } from "@hivegrid/db/pretenant-security.server";
|
||||
import { getRlsExecutionContext, runWithIsolatedUserRlsContext, runWithRlsContext } from "@hivegrid/db/rls-context.server";
|
||||
import { db } from "~/utils/db.server";
|
||||
import { TENANT_PENDING_OWNER_REASON } from "~/domain/tenant-bootstrap/tenantBootstrap.constants";
|
||||
import {
|
||||
issueReservedOwnerInvitationWithTx,
|
||||
type ReservedOwnerInvitationDraft,
|
||||
} from "~/domain/tenant-bootstrap/ownerInvitationIssuance.server";
|
||||
|
||||
export type ConvertedStatus = "trial" | "customer";
|
||||
export type ConversionPath = "self-service" | "admin-override" | "api";
|
||||
@@ -51,6 +62,8 @@ export interface ConvertLeadInput {
|
||||
};
|
||||
/** Optional acting admin user id when conversionPath === "admin-override". */
|
||||
actorId?: string | null;
|
||||
/** Prepared capability + mail content; persisted atomically with conversion. */
|
||||
ownerInvitation: ReservedOwnerInvitationDraft;
|
||||
/**
|
||||
* Optional plan-id (SubscriptionProduct.id) carried through to the
|
||||
* webhook payload — does NOT enrol the tenant into a subscription. The
|
||||
@@ -72,9 +85,10 @@ export interface ConvertLeadResult {
|
||||
export interface RecordExistingTenantLeadConversionInput {
|
||||
leadId: string;
|
||||
tenantId: string;
|
||||
targetStatus?: ConvertedStatus;
|
||||
conversionPath?: ConversionPath;
|
||||
actorId?: string | null;
|
||||
userId: string;
|
||||
expectedEmail: string;
|
||||
targetStatus?: "trial";
|
||||
conversionPath?: "self-service";
|
||||
planId?: string | null;
|
||||
}
|
||||
|
||||
@@ -105,159 +119,78 @@ export class LeadConversionDisabledError extends Error {
|
||||
export const MARKETING_LEAD_EVENT_PREFIX = "marketing.lead";
|
||||
|
||||
export function buildLeadConversionEventType(status: ConvertedStatus): string {
|
||||
return status === "customer"
|
||||
? `${MARKETING_LEAD_EVENT_PREFIX}.convertedtocustomer`
|
||||
: `${MARKETING_LEAD_EVENT_PREFIX}.convertedtotrial`;
|
||||
return status === "customer" ? `${MARKETING_LEAD_EVENT_PREFIX}.convertedtocustomer` : `${MARKETING_LEAD_EVENT_PREFIX}.convertedtotrial`;
|
||||
}
|
||||
|
||||
export async function recordExistingTenantLeadConversion(input: RecordExistingTenantLeadConversionInput): Promise<ConvertLeadResult> {
|
||||
if (process.env.LEAD_CONVERSION_ENABLED === "false") {
|
||||
throw new LeadConversionDisabledError();
|
||||
}
|
||||
const status: ConvertedStatus = input.targetStatus ?? "trial";
|
||||
const conversionPath: ConversionPath = input.conversionPath ?? "self-service";
|
||||
const status = "trial" as const;
|
||||
const conversionPath = "self-service" as const;
|
||||
|
||||
return await db.$transaction(async (tx) => {
|
||||
const lead = await tx.lead.findUnique({
|
||||
where: { id: input.leadId },
|
||||
select: {
|
||||
id: true,
|
||||
email: true,
|
||||
firstName: true,
|
||||
lastName: true,
|
||||
company: true,
|
||||
source: true,
|
||||
utmSource: true,
|
||||
utmMedium: true,
|
||||
utmCampaign: true,
|
||||
utmTerm: true,
|
||||
utmContent: true,
|
||||
gclid: true,
|
||||
fbclid: true,
|
||||
referrer: true,
|
||||
landingPage: true,
|
||||
firstSeenAt: true,
|
||||
convertedToTenantId: true,
|
||||
},
|
||||
});
|
||||
if (!lead) throw new LeadNotFoundError(input.leadId);
|
||||
if (lead.convertedToTenantId) {
|
||||
return runWithRlsContext({ tenantId: input.tenantId, userId: input.userId }, () =>
|
||||
db.$transaction(async (tx) => {
|
||||
const lead = await convertSelfServiceMarketingLeadCapability(
|
||||
{
|
||||
leadId: input.leadId,
|
||||
tenantId: input.tenantId,
|
||||
userId: input.userId,
|
||||
expectedEmail: input.expectedEmail,
|
||||
planId: input.planId,
|
||||
},
|
||||
tx as never
|
||||
);
|
||||
if (!lead) throw new LeadNotFoundError(input.leadId);
|
||||
if (lead.convertedToTenantId !== input.tenantId) {
|
||||
throw new LeadAlreadyConvertedError(lead.id, lead.convertedToTenantId);
|
||||
throw new LeadAlreadyConvertedError(lead.leadId, lead.convertedToTenantId);
|
||||
}
|
||||
if (lead.alreadyConverted) {
|
||||
return {
|
||||
tenantId: input.tenantId,
|
||||
leadId: lead.leadId,
|
||||
status,
|
||||
alreadyConverted: true,
|
||||
outboxEventId: null,
|
||||
};
|
||||
}
|
||||
|
||||
const outboxEvent = await publishOutboxEvent(tx as unknown as OutboxPublisherTransaction, {
|
||||
tenantId: input.tenantId,
|
||||
type: buildLeadConversionEventType(status),
|
||||
payload: {
|
||||
leadId: lead.leadId,
|
||||
tenantId: input.tenantId,
|
||||
targetStatus: status,
|
||||
conversionPath,
|
||||
planId: input.planId ?? null,
|
||||
email: lead.email,
|
||||
firstName: lead.firstName,
|
||||
lastName: lead.lastName,
|
||||
company: lead.company,
|
||||
utm: {
|
||||
source: lead.utmSource,
|
||||
medium: lead.utmMedium,
|
||||
campaign: lead.utmCampaign,
|
||||
term: lead.utmTerm,
|
||||
content: lead.utmContent,
|
||||
},
|
||||
referrer: lead.referrer,
|
||||
landingPage: lead.landingPage,
|
||||
convertedAt: lead.convertedAt,
|
||||
} as Prisma.InputJsonValue,
|
||||
dispatchKey: `lead-convert:${lead.leadId}`,
|
||||
});
|
||||
|
||||
return {
|
||||
tenantId: input.tenantId,
|
||||
leadId: lead.id,
|
||||
leadId: lead.leadId,
|
||||
status,
|
||||
alreadyConverted: true,
|
||||
outboxEventId: null,
|
||||
alreadyConverted: false,
|
||||
outboxEventId: outboxEvent.id,
|
||||
};
|
||||
}
|
||||
|
||||
const now = new Date();
|
||||
await tx.lead.update({
|
||||
where: { id: lead.id },
|
||||
data: {
|
||||
status,
|
||||
convertedToTenantId: input.tenantId,
|
||||
convertedAt: now,
|
||||
},
|
||||
});
|
||||
|
||||
await tx.leadEvent.create({
|
||||
data: {
|
||||
leadId: lead.id,
|
||||
type: "converted",
|
||||
actorId: input.actorId ?? null,
|
||||
payload: {
|
||||
tenantId: input.tenantId,
|
||||
conversionPath,
|
||||
targetStatus: status,
|
||||
planId: input.planId ?? null,
|
||||
} as Prisma.InputJsonValue,
|
||||
},
|
||||
});
|
||||
|
||||
await tx.tenantAcquisition.upsert({
|
||||
where: { tenantId: input.tenantId },
|
||||
create: {
|
||||
tenantId: input.tenantId,
|
||||
leadId: lead.id,
|
||||
source: lead.source ?? conversionPath,
|
||||
utmSource: lead.utmSource,
|
||||
utmMedium: lead.utmMedium,
|
||||
utmCampaign: lead.utmCampaign,
|
||||
utmTerm: lead.utmTerm,
|
||||
utmContent: lead.utmContent,
|
||||
gclid: lead.gclid,
|
||||
fbclid: lead.fbclid,
|
||||
referrer: lead.referrer,
|
||||
landingPage: lead.landingPage,
|
||||
capturedAt: lead.firstSeenAt,
|
||||
convertedAt: now,
|
||||
conversionPath,
|
||||
customFields:
|
||||
input.planId != null
|
||||
? ({ planId: input.planId } as Prisma.InputJsonValue)
|
||||
: Prisma.JsonNull,
|
||||
},
|
||||
update: {
|
||||
leadId: lead.id,
|
||||
source: lead.source ?? conversionPath,
|
||||
utmSource: lead.utmSource,
|
||||
utmMedium: lead.utmMedium,
|
||||
utmCampaign: lead.utmCampaign,
|
||||
utmTerm: lead.utmTerm,
|
||||
utmContent: lead.utmContent,
|
||||
gclid: lead.gclid,
|
||||
fbclid: lead.fbclid,
|
||||
referrer: lead.referrer,
|
||||
landingPage: lead.landingPage,
|
||||
capturedAt: lead.firstSeenAt,
|
||||
convertedAt: now,
|
||||
conversionPath,
|
||||
customFields:
|
||||
input.planId != null
|
||||
? ({ planId: input.planId } as Prisma.InputJsonValue)
|
||||
: Prisma.JsonNull,
|
||||
},
|
||||
});
|
||||
|
||||
const outboxEvent = await publishOutboxEvent(tx as unknown as OutboxPublisherTransaction, {
|
||||
tenantId: input.tenantId,
|
||||
type: buildLeadConversionEventType(status),
|
||||
payload: {
|
||||
leadId: lead.id,
|
||||
tenantId: input.tenantId,
|
||||
targetStatus: status,
|
||||
conversionPath,
|
||||
planId: input.planId ?? null,
|
||||
email: lead.email,
|
||||
firstName: lead.firstName,
|
||||
lastName: lead.lastName,
|
||||
company: lead.company,
|
||||
utm: {
|
||||
source: lead.utmSource,
|
||||
medium: lead.utmMedium,
|
||||
campaign: lead.utmCampaign,
|
||||
term: lead.utmTerm,
|
||||
content: lead.utmContent,
|
||||
},
|
||||
referrer: lead.referrer,
|
||||
landingPage: lead.landingPage,
|
||||
convertedAt: now.toISOString(),
|
||||
} as Prisma.InputJsonValue,
|
||||
dispatchKey: `lead-convert:${lead.id}`,
|
||||
});
|
||||
|
||||
return {
|
||||
tenantId: input.tenantId,
|
||||
leadId: lead.id,
|
||||
status,
|
||||
alreadyConverted: false,
|
||||
outboxEventId: outboxEvent.id,
|
||||
};
|
||||
});
|
||||
})
|
||||
);
|
||||
}
|
||||
|
||||
export async function convertLeadToTenant(input: ConvertLeadInput): Promise<ConvertLeadResult> {
|
||||
@@ -266,8 +199,16 @@ export async function convertLeadToTenant(input: ConvertLeadInput): Promise<Conv
|
||||
}
|
||||
const status: ConvertedStatus = input.targetStatus ?? "trial";
|
||||
const conversionPath: ConversionPath = input.conversionPath ?? "self-service";
|
||||
const tenantId = randomUUID();
|
||||
|
||||
const transaction = async (tx: Prisma.TransactionClient): Promise<ConvertLeadResult> => {
|
||||
// Serialize every conversion attempt for this lead before reading its
|
||||
// conversion state. The lock is transaction-scoped, so a concurrent
|
||||
// request observes the committed winner instead of creating an orphaned
|
||||
// ownerless tenant and overwriting convertedToTenantId.
|
||||
const conversionLockKey = `lead-convert:${input.leadId}`;
|
||||
await tx.$executeRaw`SELECT pg_advisory_xact_lock(hashtextextended(${conversionLockKey}, 0))`;
|
||||
|
||||
return await db.$transaction(async (tx) => {
|
||||
const lead = await tx.lead.findUnique({
|
||||
where: { id: input.leadId },
|
||||
select: {
|
||||
@@ -292,6 +233,7 @@ export async function convertLeadToTenant(input: ConvertLeadInput): Promise<Conv
|
||||
},
|
||||
});
|
||||
if (!lead) throw new LeadNotFoundError(input.leadId);
|
||||
assertLeadOwnerInvitation(input, lead);
|
||||
|
||||
// Idempotent re-run: already-converted leads return existing tenant.
|
||||
if (lead.convertedToTenantId) {
|
||||
@@ -306,9 +248,12 @@ export async function convertLeadToTenant(input: ConvertLeadInput): Promise<Conv
|
||||
|
||||
const tenant = await tx.tenant.create({
|
||||
data: {
|
||||
id: tenantId,
|
||||
name: input.tenant.name,
|
||||
slug: input.tenant.slug,
|
||||
icon: input.tenant.icon ?? undefined,
|
||||
active: false,
|
||||
deactivatedReason: TENANT_PENDING_OWNER_REASON,
|
||||
inboundAddresses: {
|
||||
create: [{ address: input.tenant.inboundAddress }],
|
||||
},
|
||||
@@ -316,6 +261,11 @@ export async function convertLeadToTenant(input: ConvertLeadInput): Promise<Conv
|
||||
select: { id: true },
|
||||
});
|
||||
|
||||
await issueReservedOwnerInvitationWithTx(tx, {
|
||||
tenantId: tenant.id,
|
||||
...input.ownerInvitation,
|
||||
});
|
||||
|
||||
const now = new Date();
|
||||
await tx.lead.update({
|
||||
where: { id: lead.id },
|
||||
@@ -358,10 +308,7 @@ export async function convertLeadToTenant(input: ConvertLeadInput): Promise<Conv
|
||||
capturedAt: lead.firstSeenAt,
|
||||
convertedAt: now,
|
||||
conversionPath,
|
||||
customFields:
|
||||
input.planId != null
|
||||
? ({ planId: input.planId } as Prisma.InputJsonValue)
|
||||
: Prisma.JsonNull,
|
||||
customFields: input.planId != null ? ({ planId: input.planId } as Prisma.InputJsonValue) : Prisma.JsonNull,
|
||||
},
|
||||
});
|
||||
|
||||
@@ -400,5 +347,37 @@ export async function convertLeadToTenant(input: ConvertLeadInput): Promise<Conv
|
||||
alreadyConverted: false,
|
||||
outboxEventId: outboxEvent.id,
|
||||
};
|
||||
});
|
||||
};
|
||||
const execute = () => runWithRlsContext({ tenantId, userId: input.actorId ?? undefined }, () => db.$transaction(transaction));
|
||||
const current = getRlsExecutionContext();
|
||||
const actorUserId = input.actorId ?? current?.userId;
|
||||
return current?.userId && current.userId === actorUserId && (current.tenantId || current.transaction)
|
||||
? runWithIsolatedUserRlsContext(current.userId, execute)
|
||||
: execute();
|
||||
}
|
||||
|
||||
function assertLeadOwnerInvitation(
|
||||
input: ConvertLeadInput,
|
||||
lead: { email: string; firstName: string | null; lastName: string | null }
|
||||
): void {
|
||||
const firstName = lead.firstName?.trim() ?? "";
|
||||
const lastName = lead.lastName?.trim() ?? "";
|
||||
if (
|
||||
!firstName ||
|
||||
!lastName ||
|
||||
input.ownerInvitation.issuanceKey !== `lead:${input.leadId}` ||
|
||||
input.ownerInvitation.email.trim().toLowerCase() !== lead.email.trim().toLowerCase() ||
|
||||
input.ownerInvitation.firstName.trim() !== firstName ||
|
||||
input.ownerInvitation.lastName.trim() !== lastName ||
|
||||
input.ownerInvitation.fromUserId !== (input.actorId ?? null)
|
||||
) {
|
||||
throw new LeadOwnerInvitationMismatchError(input.leadId);
|
||||
}
|
||||
}
|
||||
|
||||
export class LeadOwnerInvitationMismatchError extends Error {
|
||||
override readonly name = "LeadOwnerInvitationMismatchError";
|
||||
constructor(leadId: string) {
|
||||
super(`Lead ${leadId} owner invitation does not match the conversion request.`);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user