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.

Add bounded partner search candidate API

Rafi233eb416aef0
diff --git a/apps/web/lib/api/partners/search/constants.ts b/apps/web/lib/api/partners/search/constants.ts
new file mode 100644
index 0000000000..417e2bb4f1
--- /dev/null
+++ b/apps/web/lib/api/partners/search/constants.ts
@@ -0,0 +1,13 @@
+export const PARTNER_SEARCH_CANDIDATE_LIMIT = 100;
+
+export function validatePartnerSearchCandidateLimit(limit: number) {
+ if (
+ !Number.isSafeInteger(limit) ||
+ limit <= 0 ||
+ limit > PARTNER_SEARCH_CANDIDATE_LIMIT
+ ) {
+ throw new Error(
+ `Partner search candidate limit must be between 1 and ${PARTNER_SEARCH_CANDIDATE_LIMIT}.`,
+ );
+ }
+}
diff --git a/apps/web/lib/api/partners/search/index.ts b/apps/web/lib/api/partners/search/index.ts
index 64ae4ddc11..21101a1bbd 100644
--- a/apps/web/lib/api/partners/search/index.ts
+++ b/apps/web/lib/api/partners/search/index.ts
@@ -1,5 +1,6 @@
export * from "./backfill";
export * from "./build-search-query";
+export * from "./constants";
export * from "./order-search-results";
export * from "./provider";
export * from "./providers/mock";
diff --git a/apps/web/lib/api/partners/search/providers/mock.ts b/apps/web/lib/api/partners/search/providers/mock.ts
index bb10df0b15..a503616084 100644
--- a/apps/web/lib/api/partners/search/providers/mock.ts
+++ b/apps/web/lib/api/partners/search/providers/mock.ts
@@ -1,8 +1,10 @@
+import { validatePartnerSearchCandidateLimit } from "../constants";
import {
getPartnerSearchableValues,
normalizePartnerSearchQuery,
} from "../searchable-values";
import {
+ PartnerSearchCandidateQuery,
PartnerSearchCountQuery,
PartnerSearchDocument,
PartnerSearchFilters,
@@ -148,6 +150,25 @@ export function createMockPartnerSearchProvider(
);
return {
+ async searchCandidates({
+ programId,
+ query,
+ limit,
+ }: PartnerSearchCandidateQuery) {
+ validatePartnerSearchCandidateLimit(limit);
+ const matches = findMatchingDocuments(documents.values(), {
+ programId,
+ query,
+ });
+
+ return {
+ hits: matches.slice(0, limit).map((document) => ({
+ id: document.id,
+ partnerId: document.partnerId,
+ })),
+ };
+ },
+
async search({
programId,
query,
diff --git a/apps/web/lib/api/partners/search/providers/upstash-redis.ts b/apps/web/lib/api/partners/search/providers/upstash-redis.ts
index 8d41abf785..fd8c9fbebc 100644
--- a/apps/web/lib/api/partners/search/providers/upstash-redis.ts
+++ b/apps/web/lib/api/partners/search/providers/upstash-redis.ts
@@ -5,11 +5,13 @@ import {
type InferFilterFromSchema,
type SearchIndex,
} from "@upstash/redis";
+import { validatePartnerSearchCandidateLimit } from "../constants";
import {
getPartnerSearchableValues,
normalizePartnerSearchQuery,
} from "../searchable-values";
import type {
+ PartnerSearchCandidateQuery,
PartnerSearchCountQuery,
PartnerSearchDocument,
PartnerSearchGroup,
@@ -654,6 +656,38 @@ export function createUpstashRedisPartnerSearchProvider({
});
return {
+ async searchCandidates({
+ programId,
+ query,
+ limit,
+ }: PartnerSearchCandidateQuery) {
+ validatePartnerSearchCandidateLimit(limit);
+ const filter = buildUpstashFilter({ programId, query });
+ const results = await withQueryDeadline(() =>
+ queryIndex.query({
+ filter,
+ limit,
+ select: { id: true, partnerId: true },
+ }),
+ );
+ const hits = results.map(({ data, score }) => ({
+ id: data.id,
+ partnerId: data.partnerId,
+ score,
+ }));
+
+ logPartnerSearchDebug("search", {
+ indexName: resolvedIndexName,
+ operation: "searchCandidates",
+ query: { programId, query, limit },
+ filter,
+ resultCount: hits.length,
+ hits,
+ });
+
+ return { hits };
+ },
+
async search(query: PartnerSearchQuery) {
const filter = buildUpstashFilter(query);
const offset = (query.page - 1) * query.pageSize;
diff --git a/apps/web/lib/api/partners/search/providers/upstash-search.ts b/apps/web/lib/api/partners/search/providers/upstash-search.ts
index 760e782f28..cab9b859e4 100644
--- a/apps/web/lib/api/partners/search/providers/upstash-search.ts
+++ b/apps/web/lib/api/partners/search/providers/upstash-search.ts
@@ -1,5 +1,9 @@
import { chunk } from "@dub/utils";
import { Search } from "@upstash/search";
+import {
+ PARTNER_SEARCH_CANDIDATE_LIMIT,
+ validatePartnerSearchCandidateLimit,
+} from "../constants";
import { normalizePartnerSearchQuery } from "../searchable-values";
import type {
PartnerSearchCountQuery,
@@ -13,7 +17,7 @@ import type {
const DEFAULT_INDEX_NAME = "partner-search-v1";
const NULL_VALUE = "\0__null:f47ac10b-58cc-4372-a567-0e02b2c3d479__";
-const MAX_SEARCH_RESULTS = 100;
+const MAX_SEARCH_RESULTS = PARTNER_SEARCH_CANDIDATE_LIMIT;
const WRITE_BATCH_SIZE = 100;
const DELETE_BATCH_SIZE = 1_000;
const WAIT_FOR_INDEXING_TIMEOUT_MS = 30_000;
@@ -474,7 +478,7 @@ export function createUpstashSearchPartnerSearchProvider({
const index = searchIndex ?? createSearchIndex(resolvedIndexName);
const candidateCache = new Map<string, CandidateCacheEntry>();
- async function searchCandidates(
+ async function findSearchCandidates(
query: PartnerSearchCountQuery,
{ limit, requireComplete }: { limit: number; requireComplete: boolean },
): Promise<UpstashSearchResult[]> {
@@ -529,7 +533,7 @@ export function createUpstashSearchPartnerSearchProvider({
candidateCache.delete(candidateCache.keys().next().value!);
}
- const promise = searchCandidates(query, {
+ const promise = findSearchCandidates(query, {
limit: MAX_SEARCH_RESULTS,
requireComplete: true,
}).catch((error) => {
@@ -546,6 +550,29 @@ export function createUpstashSearchPartnerSearchProvider({
return {
mode: "relevance-only",
+ async searchCandidates({ programId, query, limit }) {
+ validatePartnerSearchCandidateLimit(limit);
+ const candidates = await findSearchCandidates(
+ { programId, query },
+ { limit, requireComplete: false },
+ );
+ const hits = candidates
+ .slice(0, limit)
+ .flatMap(({ id, metadata, score }) =>
+ metadata ? [{ id, partnerId: metadata.partnerId, score }] : [],
+ );
+
+ logPartnerSearchDebug("search", {
+ indexName: resolvedIndexName,
+ operation: "searchCandidates",
+ query: { programId, query, limit },
+ resultCount: hits.length,
+ hits,
+ });
+
+ return { hits };
+ },
+
async search(query) {
const { sort } = query;
if (sort) {
@@ -579,7 +606,7 @@ export function createUpstashSearchPartnerSearchProvider({
// Upstash Search natively returns relevance-ranked results. Fetch enough
// results to derive the requested page without requiring a complete set.
- const candidates = await searchCandidates(query, {
+ const candidates = await findSearchCandidates(query, {
limit: requestedResults,
requireComplete: false,
});
diff --git a/apps/web/lib/api/partners/search/types.ts b/apps/web/lib/api/partners/search/types.ts
index 8283d2266f..32f2c8d313 100644
--- a/apps/web/lib/api/partners/search/types.ts
+++ b/apps/web/lib/api/partners/search/types.ts
@@ -128,8 +128,17 @@ export interface PartnerSearchResult {
hits: PartnerSearchHit[];
}
+export interface PartnerSearchCandidateQuery {
+ programId: string;
+ query: string;
+ limit: number;
+}
+
export interface PartnerSearchProvider {
mode?: "full" | "relevance-only";
+ searchCandidates(
+ query: PartnerSearchCandidateQuery,
+ ): Promise<PartnerSearchResult>;
search(query: PartnerSearchQuery): Promise<PartnerSearchResult>;
count(query: PartnerSearchCountQuery): Promise<number>;
groupBy(
diff --git a/apps/web/tests/partners/get-partners-count-search.test.ts b/apps/web/tests/partners/get-partners-count-search.test.ts
index a62c0e6929..5126721fdb 100644
--- a/apps/web/tests/partners/get-partners-count-search.test.ts
+++ b/apps/web/tests/partners/get-partners-count-search.test.ts
@@ -6,6 +6,7 @@ vi.mock("@/lib/prisma", () => ({ prisma: {} }));
function createSearchProvider(): PartnerSearchProvider {
return {
+ searchCandidates: vi.fn(),
search: vi.fn(),
count: vi.fn().mockResolvedValue(2),
groupBy: vi.fn().mockResolvedValue([{ value: "approved", count: 2 }]),
diff --git a/apps/web/tests/partners/get-partners-search.test.ts b/apps/web/tests/partners/get-partners-search.test.ts
index 9d4f00e89b..8465745456 100644
--- a/apps/web/tests/partners/get-partners-search.test.ts
+++ b/apps/web/tests/partners/get-partners-search.test.ts
@@ -43,6 +43,7 @@ describe("getPartners search", () => {
enrollment("pge_2", "pn_2"),
]);
const searchProvider: PartnerSearchProvider = {
+ searchCandidates: vi.fn(),
search: vi.fn().mockResolvedValue({
hits: [
{ id: "pge_2", partnerId: "pn_2" },
@@ -89,6 +90,7 @@ describe("getPartners search", () => {
it("propagates search provider errors", async () => {
const searchProvider: PartnerSearchProvider = {
+ searchCandidates: vi.fn(),
search: vi
.fn()
.mockRejectedValue(new Error("Provider Connection Timeout")),
diff --git a/apps/web/tests/partners/partner-search-backfill.test.ts b/apps/web/tests/partners/partner-search-backfill.test.ts
index 127b128aed..1cbdbdc1e6 100644
--- a/apps/web/tests/partners/partner-search-backfill.test.ts
+++ b/apps/web/tests/partners/partner-search-backfill.test.ts
@@ -59,6 +59,7 @@ function createSource(id: string): PartnerSearchDocumentSource {
function createProvider(): PartnerSearchProvider {
return {
+ searchCandidates: vi.fn(),
search: vi.fn(),
count: vi.fn(),
groupBy: vi.fn(),
@@ -143,6 +144,7 @@ describe("backfillPartnerSearch", () => {
await expect(
backfillPartnerSearch({
programId: "prog_test",
+ searchProvider: null,
}),
).rejects.toThrow("Partner search provider is not configured.");
diff --git a/apps/web/tests/partners/partner-search-provider.test.ts b/apps/web/tests/partners/partner-search-provider.test.ts
index 90ee67c7dc..2fed1b2cea 100644
--- a/apps/web/tests/partners/partner-search-provider.test.ts
+++ b/apps/web/tests/partners/partner-search-provider.test.ts
@@ -1,5 +1,6 @@
import {
createMockPartnerSearchProvider,
+ PARTNER_SEARCH_CANDIDATE_LIMIT,
PartnerSearchDocument,
} from "@/lib/api/partners/search";
import { describe, expect, it } from "vitest";
@@ -65,6 +66,14 @@ describe("partner search provider contract", () => {
expect(result.hits).toHaveLength(1);
expect(result.hits[0]?.partnerId).toBe(partnerDocument.partnerId);
+
+ const candidates = await provider.searchCandidates({
+ programId: partnerDocument.programId,
+ query,
+ limit: PARTNER_SEARCH_CANDIDATE_LIMIT,
+ });
+ expect(candidates.hits).toHaveLength(1);
+ expect(candidates.hits[0]?.partnerId).toBe(partnerDocument.partnerId);
});
it("keeps search results scoped to a program", async () => {
@@ -78,6 +87,40 @@ describe("partner search provider contract", () => {
});
expect(result).toEqual({ hits: [] });
+ await expect(
+ provider.searchCandidates({
+ programId: "prog_other",
+ query: "rafi",
+ limit: PARTNER_SEARCH_CANDIDATE_LIMIT,
+ }),
+ ).resolves.toEqual({ hits: [] });
+ });
+
+ it("bounds relevance candidates to the shared provider limit", async () => {
+ const documents = Array.from(
+ { length: PARTNER_SEARCH_CANDIDATE_LIMIT + 1 },
+ (_, index) => ({
+ ...partnerDocument,
+ id: `pge_${index}`,
+ partnerId: `pn_${index}`,
+ }),
+ );
+ const provider = createMockPartnerSearchProvider(documents);
+
+ const result = await provider.searchCandidates({
+ programId: partnerDocument.programId,
+ query: "rafi",
+ limit: PARTNER_SEARCH_CANDIDATE_LIMIT,
+ });
+ expect(result.hits).toHaveLength(PARTNER_SEARCH_CANDIDATE_LIMIT);
+ expect(result.hits[0]).toEqual(expect.objectContaining({ id: "pge_0" }));
+ await expect(
+ provider.searchCandidates({
+ programId: partnerDocument.programId,
+ query: "rafi",
+ limit: PARTNER_SEARCH_CANDIDATE_LIMIT + 1,
+ }),
+ ).rejects.toThrow("must be between 1 and 100");
});
it("combines search with filters", async () => {
diff --git a/apps/web/tests/partners/partner-search-sync.test.ts b/apps/web/tests/partners/partner-search-sync.test.ts
index 975f7288c9..c04ce26f8f 100644
--- a/apps/web/tests/partners/partner-search-sync.test.ts
+++ b/apps/web/tests/partners/partner-search-sync.test.ts
@@ -62,6 +62,7 @@ function createSource(id: string): PartnerSearchDocumentSource {
function createProvider(): PartnerSearchProvider {
return {
+ searchCandidates: vi.fn(),
search: vi.fn(),
count: vi.fn(),
groupBy: vi.fn(),
@@ -77,7 +78,9 @@ describe("partner search document sync", () => {
});
it("does nothing when no provider is configured", async () => {
- await syncPartnerSearchDocuments(["pge_1"]);
+ await syncPartnerSearchDocuments(["pge_1"], {
+ searchProvider: null,
+ });
expect(mocks.findMany).not.toHaveBeenCalled();
});
diff --git a/apps/web/tests/partners/upstash-redis-partner-search-provider.test.ts b/apps/web/tests/partners/upstash-redis-partner-search-provider.test.ts
index 8eae33804e..2a60189fd4 100644
--- a/apps/web/tests/partners/upstash-redis-partner-search-provider.test.ts
+++ b/apps/web/tests/partners/upstash-redis-partner-search-provider.test.ts
@@ -1,6 +1,7 @@
import {
createUpstashRedisPartnerSearchIndex,
createUpstashRedisPartnerSearchProvider,
+ PARTNER_SEARCH_CANDIDATE_LIMIT,
type PartnerSearchDocument,
upstashPartnerSearchSchema,
} from "@/lib/api/partners/search";
@@ -123,6 +124,43 @@ describe("Upstash Redis partner search provider", () => {
mocks.waitIndexing.mockResolvedValue(1);
});
+ it("retrieves bounded relevance candidates without business filters", async () => {
+ mocks.query.mockResolvedValue([
+ {
+ key: "test-index:partner:pge_test",
+ score: 4,
+ data: { id: document.id, partnerId: document.partnerId },
+ },
+ ]);
+ const provider = createUpstashRedisPartnerSearchProvider({
+ redisClient: createRedisMock(),
+ indexName: "test-index",
+ });
+
+ await expect(
+ provider.searchCandidates({
+ programId: document.programId,
+ query: "rafi",
+ limit: PARTNER_SEARCH_CANDIDATE_LIMIT,
+ }),
+ ).resolves.toEqual({
+ hits: [{ id: document.id, partnerId: document.partnerId, score: 4 }],
+ });
+
+ expect(mocks.query).toHaveBeenCalledWith(
+ expect.objectContaining({
+ limit: PARTNER_SEARCH_CANDIDATE_LIMIT,
+ select: { id: true, partnerId: true },
+ }),
+ );
+ const request = mocks.query.mock.calls[0]![0];
+ expect(request.offset).toBeUndefined();
+ expect(request.orderBy).toBeUndefined();
+ expect(JSON.stringify(request.filter)).toContain(
+ '"programId":{"$eq":"prog_test"}',
+ );
+ });
+
it("searches within the program and supports partial email matching", async () => {
mocks.query.mockResolvedValue([
{
diff --git a/apps/web/tests/partners/upstash-search-partner-search-provider.test.ts b/apps/web/tests/partners/upstash-search-partner-search-provider.test.ts
index 6e3deecd87..8ce6d0fd92 100644
--- a/apps/web/tests/partners/upstash-search-partner-search-provider.test.ts
+++ b/apps/web/tests/partners/upstash-search-partner-search-provider.test.ts
@@ -226,6 +226,16 @@ describe("Upstash Search partner search provider", () => {
expect(mocks.search).toHaveBeenCalledWith(
expect.objectContaining({ query: "drew moore", limit: 10 }),
);
+
+ const candidates = await provider.searchCandidates({
+ programId: document.programId,
+ query: "drew moore",
+ limit: 10,
+ });
+ expect(candidates.hits).toHaveLength(10);
+ expect(mocks.search).toHaveBeenLastCalledWith(
+ expect.objectContaining({ query: "drew moore", limit: 10 }),
+ );
});
it("shares candidates across search, count, and grouping", async () => {