Skip to content

armgit / dub

Public Imported from GitHub
0

The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.

Search relevance parameter documentation

Rafi3aafe1d5a4db
diff --git a/apps/web/app/(ee)/api/partners/route.ts b/apps/web/app/(ee)/api/partners/route.ts
index cb5ec695c8..fb1b6feb32 100644
--- a/apps/web/app/(ee)/api/partners/route.ts
+++ b/apps/web/app/(ee)/api/partners/route.ts
@@ -9,7 +9,7 @@ import { polyfillSocialMediaFields } from "@/lib/social-utils";
import {
createPartnerSchema,
EnrolledPartnerSchema,
- getPartnersQuerySchemaExtended,
+ getPartnersRouteQuerySchema,
partnerPlatformSchema,
} from "@/lib/zod/schemas/partners";
import { parseFilterValue, toCentsNumber } from "@dub/utils";
@@ -51,21 +51,7 @@ export const GET = withWorkspace(
}),
};
const { sortBy: sortByWithOldFields, ...parsedParams } =
- getPartnersQuerySchemaExtended
- .extend({
- // add old fields for backward compatibility
- sortBy: getPartnersQuerySchemaExtended.shape.sortBy.or(
- z.enum([
- "clicks",
- "leads",
- "conversions",
- "sales",
- "saleAmount",
- "totalSales",
- ]),
- ),
- })
- .parse(paramsToParse);
+ getPartnersRouteQuerySchema.parse(paramsToParse);
// get the final sortBy field (replace old fields with new fields)
const sortBy =
diff --git a/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/partners-table.tsx b/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/partners-table.tsx
index ea66d9aa25..d4dd3bc35d 100644
--- a/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/partners-table.tsx
+++ b/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/partners-table.tsx
@@ -117,6 +117,9 @@ const partnersColumns = {
],
};
+// Searching must fall back to relevance ordering. A column sort still applies to
+// the same relevance-ranked candidates, but it reorders them, so the best match
+// lands somewhere down the list instead of first — which reads as broken search.
const PARTNER_SEARCH_RESET_PARAMS = ["sortBy", "sortOrder"];
const getPartnerUrl = ({
@@ -135,14 +138,18 @@ export function PartnersTable() {
const { id: workspaceId, slug: workspaceSlug } = useWorkspace();
const { program } = useProgram();
+ // A blank query is not searchable, and asking for relevance without one is a
+ // 400 from the API.
+ const search = searchParams.get("search")?.trim();
+
const status =
- searchParams.get("status") || searchParams.get("search")
+ searchParams.get("status") || search
? undefined
: ProgramEnrollmentStatus.approved;
const sortBy =
searchParams.get("sortBy") ||
- (searchParams.get("search")
+ (search
? "relevance"
: program?.primaryRewardEvent === "lead"
? "totalLeads"
diff --git a/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/use-partner-filters.tsx b/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/use-partner-filters.tsx
index 51537bda51..4d305a0bc4 100644
--- a/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/use-partner-filters.tsx
+++ b/apps/web/app/app.dub.co/(dashboard)/[slug]/(ee)/program/partners/use-partner-filters.tsx
@@ -169,7 +169,7 @@ export function usePartnerFilters(
const { id: workspaceId, slug } = useWorkspace();
const status = (searchParamsObj.status ||
extraSearchParams.status ||
- (searchParamsObj.search ? undefined : "approved")) as
+ (searchParamsObj.search?.trim() ? undefined : "approved")) as
| ProgramEnrollmentStatus
| undefined;
diff --git a/apps/web/lib/zod/schemas/partners.ts b/apps/web/lib/zod/schemas/partners.ts
index fa5a462e6f..3d34c321bd 100644
--- a/apps/web/lib/zod/schemas/partners.ts
+++ b/apps/web/lib/zod/schemas/partners.ts
@@ -188,14 +188,14 @@ export const getPartnersQuerySchema = z
.string()
.optional()
.describe(
- "Filter the partner list based on the partner's `tenantId`. The value must be a string. Takes precedence over `email` and `search`.",
+ "Filter the partner list based on the partner's `tenantId`. The value must be a string. Combines with the other filters.",
)
.meta({ example: "1K0NM7HCN944PEMZ3CQPH43H8" }),
search: z
.string()
.optional()
.describe(
- "A search query to filter partners by ID, name, email, or company name.",
+ "A search query to filter partners by ID, name, email, company name, description, social platforms, or referral links. Partial matches are supported.",
)
.meta({ example: "john" }),
})
@@ -281,6 +281,46 @@ export const getPartnersQuerySchemaExtended = getPartnersQuerySchema.extend({
.describe("Maximum total commissions (inclusive) in USD cents."),
});
+/**
+ * Parse schema for `GET /api/partners`. Kept here rather than inline in the
+ * route so the relevance guards below are testable.
+ */
+export const getPartnersRouteQuerySchema = getPartnersQuerySchemaExtended
+ .extend({
+ // Also accept the sort values these columns were named before, which the
+ // route maps onto the current ones (`clicks` → `totalClicks`, and so on).
+ sortBy: getPartnersQuerySchemaExtended.shape.sortBy.or(
+ z.enum([
+ "clicks",
+ "leads",
+ "conversions",
+ "sales",
+ "saleAmount",
+ "totalSales",
+ ]),
+ ),
+ })
+ // Relevance ordering only exists when the search provider produced candidates,
+ // and `email` and `tenantId` both keep the query on the database path. Without
+ // this, getPartners quietly orders those results by totalSaleAmount instead.
+ .refine(
+ ({ sortBy, search, email, tenantId }) =>
+ sortBy !== "relevance" ||
+ (Boolean(search?.trim()) && !email && !tenantId),
+ {
+ message:
+ "sortBy=relevance requires a non-empty search, and cannot be combined with email or tenantId.",
+ path: ["sortBy"],
+ },
+ )
+ .refine(
+ ({ sortBy, sortOrder }) => sortBy !== "relevance" || sortOrder !== "asc",
+ {
+ message: "sortBy=relevance does not support sortOrder=asc.",
+ path: ["sortOrder"],
+ },
+ );
+
export const partnersExportQuerySchema = getPartnersQuerySchemaExtended
.omit({ page: true, pageSize: true })
.extend({
diff --git a/apps/web/tests/partners/get-partners-route-query.test.ts b/apps/web/tests/partners/get-partners-route-query.test.ts
new file mode 100644
index 0000000000..976892afee
--- /dev/null
+++ b/apps/web/tests/partners/get-partners-route-query.test.ts
@@ -0,0 +1,59 @@
+import { getPartnersRouteQuerySchema } from "@/lib/zod/schemas/partners";
+import { describe, expect, it } from "vitest";
+
+const accepts = (params: Record<string, unknown>) =>
+ getPartnersRouteQuerySchema.safeParse(params).success;
+
+describe("getPartnersRouteQuerySchema", () => {
+ it("accepts the shapes the partners table sends", () => {
+ expect(accepts({ sortBy: "relevance", search: "examp" })).toBe(true);
+ expect(
+ accepts({ sortBy: "relevance", search: "examp", sortOrder: "desc" }),
+ ).toBe(true);
+ expect(accepts({ search: "examp" })).toBe(true);
+ expect(accepts({ sortBy: "totalClicks", sortOrder: "asc" })).toBe(true);
+ expect(accepts({ email: "[email protected]" })).toBe(true);
+ expect(accepts({ tenantId: "tenant_1" })).toBe(true);
+ });
+
+ it("still accepts the legacy sort aliases", () => {
+ for (const sortBy of ["clicks", "leads", "conversions", "saleAmount"]) {
+ expect(accepts({ sortBy })).toBe(true);
+ }
+ });
+
+ it("rejects relevance without a query the provider can rank", () => {
+ expect(accepts({ sortBy: "relevance" })).toBe(false);
+ expect(accepts({ sortBy: "relevance", search: "" })).toBe(false);
+ expect(accepts({ sortBy: "relevance", search: " " })).toBe(false);
+ });
+
+ it("rejects relevance alongside an exact email lookup", () => {
+ expect(
+ accepts({ sortBy: "relevance", search: "examp", email: "[email protected]" }),
+ ).toBe(false);
+ });
+
+ it("rejects relevance alongside a tenant filter", () => {
+ expect(
+ accepts({ sortBy: "relevance", search: "examp", tenantId: "t_1" }),
+ ).toBe(false);
+ });
+
+ it("rejects ascending relevance", () => {
+ expect(
+ accepts({ sortBy: "relevance", search: "examp", sortOrder: "asc" }),
+ ).toBe(false);
+ });
+
+ it("explains why the request was rejected", () => {
+ const result = getPartnersRouteQuerySchema.safeParse({
+ sortBy: "relevance",
+ });
+
+ expect(result.success).toBe(false);
+ expect(result.error?.issues[0].message).toContain(
+ "sortBy=relevance requires a non-empty search",
+ );
+ });
+});
diff --git a/apps/web/tests/partners/get-partners-search.test.ts b/apps/web/tests/partners/get-partners-search.test.ts
index db3205cf5c..05d5be9e50 100644
--- a/apps/web/tests/partners/get-partners-search.test.ts
+++ b/apps/web/tests/partners/get-partners-search.test.ts
@@ -51,6 +51,34 @@ describe("getPartners search", () => {
mocks.findMany.mockReset();
});
+ it("keeps a tenant filter on the database search path", async () => {
+ // tenantId predates the search provider, so `tenantId` + `search` still
+ // resolves entirely in the database rather than inheriting the candidate
+ // ceiling.
+ mocks.findMany.mockResolvedValue([enrollment("pge_1", "pn_1")]);
+ const searchProvider = createSearchProvider([{ id: "pge_1" }]);
+
+ await getPartners(
+ {
+ programId: "prog_test",
+ search: "examp",
+ tenantId: "tenant_1",
+ page: 1,
+ pageSize: 25,
+ sortBy: "totalSaleAmount",
+ sortOrder: "desc",
+ },
+ { searchProvider },
+ );
+
+ expect(searchProvider.searchCandidates).not.toHaveBeenCalled();
+
+ const { where } = mocks.findMany.mock.calls.at(-1)![0];
+ expect(where).toMatchObject({ tenantId: "tenant_1" });
+ expect(where.id).toBeUndefined();
+ expect(JSON.stringify(where)).toContain('"search":"examp"');
+ });
+
it("lets the database filter, sort, and paginate search candidates", async () => {
mocks.findMany.mockResolvedValue([
enrollment("pge_1", "pn_1"),
diff --git a/apps/web/ui/shared/search-box.tsx b/apps/web/ui/shared/search-box.tsx
index 6e4f865e15..2a2fc25e76 100644
--- a/apps/web/ui/shared/search-box.tsx
+++ b/apps/web/ui/shared/search-box.tsx
@@ -96,7 +96,6 @@ export const SearchBox = forwardRef(
{showClearButton && value.length > 0 && (
<button
onClick={() => {
- debounced.cancel();
onChange("");
onChangeDebounced?.("");
}}
@@ -118,6 +117,7 @@ export function SearchBoxPersisted({
...props
}: {
urlParam?: string;
+ /** Params to clear whenever the search changes, e.g. a stale sort. */
resetParamsOnChange?: string[];
} & Partial<SearchBoxProps>) {
const { queryParams, searchParams } = useRouterStuff();
@@ -127,7 +127,7 @@ export function SearchBoxPersisted({
// Set URL param when debounced value changes
useEffect(() => {
- if ((searchParams.get(urlParam) ?? "") !== debouncedValue)
+ if (searchParams.get(urlParam) ?? "" !== debouncedValue)
queryParams(
debouncedValue === ""
? { del: [urlParam, "page", ...resetParamsOnChange] }
@@ -142,7 +142,7 @@ export function SearchBoxPersisted({
useEffect(() => {
const search = searchParams.get(urlParam);
// Only update if the value and debouncedValue are synced (the user isn't actively typing)
- if ((search ?? "") !== value && value === debouncedValue)
+ if ((search ?? "" !== value) && value === debouncedValue)
setValue(search ?? "");
}, [searchParams.get(urlParam)]);