apps/web/lib/api/conversions/track-lead.ts (1)

52-60: Align error message with new "empty string sentinel" semantics

The guard now explicitly treats empty string as "missing"; update the error text to avoid confusion.

-          "The `clickId` property was not provided in the request, and no existing customer with the provided `customerExternalId` was found.",
+          "The `clickId` was empty or missing, and no existing customer with the provided `customerExternalId` was found.",

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

diff --git a/apps/web/app/(ee)/api/track/lead/client/route.ts b/apps/web/app/(ee)/api/track/lead/client/route.ts
index 03ad1093c..588bfd2cb 100644
--- a/apps/web/app/(ee)/api/track/lead/client/route.ts
+++ b/apps/web/app/(ee)/api/track/lead/client/route.ts
@@ -9,6 +9,7 @@ import { parseRequestBody } from "@/lib/api/utils";
 import { withPublishableKey } from "@/lib/auth/publishable-key";
 import { trackLeadRequestSchema } from "@/lib/zod/schemas/leads";
 import { NextResponse } from "next/server";
+import { z } from "zod";
 
 // POST /api/track/lead/client – Track a lead conversion event on the client side
 export const POST = withPublishableKey(
@@ -37,10 +38,17 @@ export const POST = withPublishableKey(
       customerAvatar,
       mode,
       metadata,
-    } = trackLeadRequestSchema.parse(body);
+    } = trackLeadRequestSchema
+      .extend({
+        // we if clickId is undefined/nullish, we'll coerce into an empty string
+        clickId: z.string().nullish(),
+        // add backwards compatibility
+        customerExternalId: z.string().nullish(),
+      })
+      .parse(body);
 
     const response = await trackLead({
-      clickId,
+      clickId: clickId ?? "",
       eventName,
       eventQuantity,
       customerExternalId,

Analysis

API Route Inconsistency: clickId Field Validation Bug

Summary

A backwards compatibility issue exists between two lead tracking API routes where the /api/track/lead/client endpoint rejects requests with null or missing clickId values that the main /api/track/lead endpoint accepts.

Technical Details

Root Cause

The issue stems from inconsistent schema validation patterns:

• Main route (/api/track/lead/route.ts): Uses an extended schema that allows clickId to be nullish() for backwards compatibility
• Client route (/api/track/lead/client/route.ts): Uses the base trackLeadRequestSchema directly, which requires clickId as a non-null string

Schema Validation Behavior

The base trackLeadRequestSchema defines clickId as:

clickId: z.string().trim()

This requires a string value and rejects null, undefined, or missing values.

The main route extends this schema:

trackLeadRequestSchema.extend({
  clickId: z.string().nullish(),
  // other backwards compatibility fields...
})

This allows null and undefined values, which are then coerced to empty strings.

Validation Evidence

Testing confirmed the inconsistency:

• Base schema (client route): ❌ Rejects null clickId with "Expected string, received null"
• Base schema (client route): ❌ Rejects missing clickId with "Required"
• Extended schema (main route): ✅ Accepts both null and missing clickId values

Impact

Breaking Change for Client Integrations: Existing client applications using /api/track/lead/client that previously omitted the clickId field or sent null values will now receive validation errors, potentially breaking their lead tracking functionality.

API Inconsistency: The same request payload behaves differently across the two endpoints, violating the principle of least surprise and creating confusion for developers.

Solution

Applied the same schema extension pattern used in the main route to the client route:

1. Added Zod import: import { z } from "zod";

2. Extended the schema: Applied the same .extend() pattern with clickId: z.string().nullish()

3. Added null coercion: Convert null/undefined clickId values to empty strings: clickId: clickId ?? ""

This ensures both routes handle clickId consistently while maintaining backwards compatibility with existing integrations.

References

• Zod Schema Extension Documentation - Confirms .extend() is the correct pattern for schema modification
• API Backwards Compatibility Best Practices - Validates that maintaining field compatibility across endpoints is essential

diff --git a/apps/web/app/(ee)/api/track/lead/client/route.ts b/apps/web/app/(ee)/api/track/lead/client/route.ts
index 03ad1093c..0d4b3c857 100644
--- a/apps/web/app/(ee)/api/track/lead/client/route.ts
+++ b/apps/web/app/(ee)/api/track/lead/client/route.ts
@@ -9,6 +9,7 @@ import { parseRequestBody } from "@/lib/api/utils";
 import { withPublishableKey } from "@/lib/auth/publishable-key";
 import { trackLeadRequestSchema } from "@/lib/zod/schemas/leads";
 import { NextResponse } from "next/server";
+import { z } from "zod";
 
 // POST /api/track/lead/client – Track a lead conversion event on the client side
 export const POST = withPublishableKey(
@@ -37,10 +38,15 @@ export const POST = withPublishableKey(
       customerAvatar,
       mode,
       metadata,
-    } = trackLeadRequestSchema.parse(body);
+    } = trackLeadRequestSchema
+      .extend({
+        // we if clickId is undefined/nullish, we'll coerce into an empty string
+        clickId: z.string().trim().nullish(),
+      })
+      .parse(body);
 
     const response = await trackLead({
-      clickId,
+      clickId: clickId ?? "",
       eventName,
       eventQuantity,
       customerExternalId,

Analysis

API Inconsistency: Client Route Requires Optional clickId Field

Bug Summary

The /api/track/lead/client endpoint incorrectly requires the clickId field, while the main /api/track/lead endpoint correctly treats it as optional. This creates an API inconsistency and breaks existing clients that don't provide clickId.

Technical Analysis

Schema Definition

The base trackLeadRequestSchema in apps/web/lib/zod/schemas/leads.ts defines clickId as:

clickId: z.string().trim()

This makes clickId required by default (no .nullish() or .optional()).

Route Implementations

Main Route (/api/track/lead):

• ✅ Correctly handles optional clickId
• Uses trackLeadRequestSchema.extend({ clickId: z.string().trim().nullish() })
• Provides fallback: clickId: clickId ?? ""

Client Route (/api/track/lead/client):

• ❌ Incorrectly requires clickId
• Uses trackLeadRequestSchema.parse(body) directly
• No schema extension to make clickId optional

Validation Results

Testing confirmed the issue using Zod schema validation:

// Client route behavior (BEFORE fix)
trackLeadRequestSchema.parse({
  eventName: "Sign up",
  customerExternalId: "user123"
  // No clickId provided
});
// ❌ Error: "Required"

// Main route behavior 
trackLeadRequestSchema.extend({ 
  clickId: z.string().trim().nullish() 
}).parse({
  eventName: "Sign up", 
  customerExternalId: "user123"
});
// ✅ Success: clickId = undefined

Impact

• Breaking Change: Existing clients using /api/track/lead/client without clickId will fail with validation errors
• API Inconsistency: Two endpoints with different requirements for the same field
• Developer Confusion: Inconsistent behavior between similar endpoints

Solution

Applied the same schema extension pattern used in the main route to the client route:

1. Added Zod import: import { z } from "zod"
2. Extended schema: Used .extend({ clickId: z.string().trim().nullish() })
3. Added fallback: Used clickId: clickId ?? "" in the trackLead call

This ensures both endpoints behave identically and maintain backward compatibility.

Verification

Post-fix testing shows both routes now handle optional clickId consistently:

• ✅ Requests without clickId succeed (coerced to empty string)
• ✅ Requests with clickId work as before
• ✅ No breaking changes for existing clients