The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
Search relevance parameter documentation
Rafi3aafe1d5a4db
diff --git a/apps/web/app/(ee)/api/partners/route.ts b/apps/web/app/(ee)/api/partners/route.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsxindex 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 && (<buttononClick={() => {- 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 changesuseEffect(() => {- 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)]);