The modern link attribution platform. Loved by world-class engineering teams at Twilio, Zillow, Jobber, Vercel, Raycast, and more.
TypeScript clickhousemysqlnextjsopen-sourceplanetscaleprismatailwindcsstinybirdtypescriptupstashvercel
Add metadata query filtering for commissions list and count.
Kiran K0de8fcd050d7
diff --git a/apps/web/lib/api/commissions/get-commissions-count.ts b/apps/web/lib/api/commissions/get-commissions-count.tsindex 7511e90ef0..65a28ed824 100644--- a/apps/web/lib/api/commissions/get-commissions-count.ts+++ b/apps/web/lib/api/commissions/get-commissions-count.ts@@ -5,6 +5,10 @@ import { parseFilterValue } from "@dub/utils";import { CommissionStatus, CommissionType } from "@prisma/client";import * as z from "zod/v4";import { getFraudEventGroupEventIds } from "../fraud/get-fraud-event-group-event-ids";+import {+ buildCommissionMetadataWhere,+ parseCommissionMetadataQuery,+} from "./metadata-filters";type CommissionsCountFilters = z.infer<typeof getCommissionsCountQuerySchema@@ -28,6 +32,7 @@ export async function getCommissionsCount(filters: CommissionsCountFilters) {interval,timezone,programId,+ query,} = filters;// Filter the commissions based on the risk event group@@ -79,6 +84,10 @@ export async function getCommissionsCount(filters: CommissionsCountFilters) {const customerFilter = parseFilterValue(customerId);const typeFilter = parseFilterValue(type);+ // Metadata filter+ const parsedMetadataQuery = parseCommissionMetadataQuery(query);+ const metadataWhere = buildCommissionMetadataWhere(parsedMetadataQuery);+const commissionsCount = await prisma.commission.groupBy({by: ["status"],where: {@@ -118,6 +127,7 @@ export async function getCommissionsCount(filters: CommissionsCountFilters) {...(Object.keys(programEnrollmentFilter).length > 0 && {programEnrollment: programEnrollmentFilter,}),+ ...metadataWhere,},_count: true,_sum: {diff --git a/apps/web/lib/api/commissions/get-commissions.ts b/apps/web/lib/api/commissions/get-commissions.tsindex 50c19aa5f7..9289771e16 100644--- a/apps/web/lib/api/commissions/get-commissions.ts+++ b/apps/web/lib/api/commissions/get-commissions.ts@@ -2,11 +2,15 @@ import { getStartEndDates } from "@/lib/analytics/utils/get-start-end-dates";import { prisma } from "@/lib/prisma";import { getCommissionsQuerySchema } from "@/lib/zod/schemas/commissions";import { parseFilterValue } from "@dub/utils";-import { CommissionStatus, CommissionType } from "@prisma/client";+import { CommissionStatus, CommissionType, Prisma } from "@prisma/client";import * as z from "zod/v4";import { DubApiError } from "../errors";import { getFraudEventGroupEventIds } from "../fraud/get-fraud-event-group-event-ids";import { buildPaginationQuery } from "../pagination";+import {+ buildCommissionMetadataWhere,+ parseCommissionMetadataQuery,+} from "./metadata-filters";type CommissionsFilters = Omit<z.infer<typeof getCommissionsQuerySchema>,@@ -17,6 +21,17 @@ type CommissionsFilters = Omit<fraudEventGroupId?: string;};+const commissionIncludes: Prisma.CommissionInclude = {+ customer: true,+ partner: true,+ programEnrollment: true,+ payout: {+ select: {+ paidAt: true,+ },+ },+};+export async function getCommissions(filters: CommissionsFilters) {const {invoiceId,@@ -35,8 +50,22 @@ export async function getCommissions(filters: CommissionsFilters) {timezone,startingAfter,endingBefore,+ query,} = filters;+ // InvoiceId is unique within a program+ if (invoiceId) {+ return await prisma.commission.findMany({+ where: {+ invoiceId,+ programId,+ },+ include: {+ ...commissionIncludes,+ },+ });+ }+const paginationQuery = buildPaginationQuery(filters);// Validate the provided cursor ID@@ -130,45 +159,45 @@ export async function getCommissions(filters: CommissionsFilters) {}),};+ // Metadata filter+ const parsedMetadataQuery = parseCommissionMetadataQuery(query);+ const metadataWhere = buildCommissionMetadataWhere(parsedMetadataQuery);+return await prisma.commission.findMany({- where: invoiceId- ? {- invoiceId,- programId,- }- : {- earnings: {- not: 0,- },- programId,- ...(partnerFilter && {- partnerId:- partnerFilter.sqlOperator === "NOT IN"- ? { notIn: partnerFilter.values }- : { in: partnerFilter.values },- }),- status: statusFilter,- ...(typeFilter && {- type:- typeFilter.sqlOperator === "NOT IN"- ? { notIn: typeFilter.values }- : { in: typeFilter.values },- }),- customerId,- payoutId,- ...(eventIds && {- eventId: {- in: eventIds,- },- }),- createdAt: {- gte: startDate,- lte: endDate,- },- ...(Object.keys(programEnrollmentFilter).length > 0 && {- programEnrollment: programEnrollmentFilter,- }),+ where: {+ earnings: {+ not: 0,+ },+ programId,+ ...(partnerFilter && {+ partnerId:+ partnerFilter.sqlOperator === "NOT IN"+ ? { notIn: partnerFilter.values }+ : { in: partnerFilter.values },+ }),+ status: statusFilter,+ ...(typeFilter && {+ type:+ typeFilter.sqlOperator === "NOT IN"+ ? { notIn: typeFilter.values }+ : { in: typeFilter.values },+ }),+ customerId,+ payoutId,+ ...(eventIds && {+ eventId: {+ in: eventIds,},+ }),+ createdAt: {+ gte: startDate,+ lte: endDate,+ },+ ...(Object.keys(programEnrollmentFilter).length > 0 && {+ programEnrollment: programEnrollmentFilter,+ }),+ ...metadataWhere,+ },include: {customer: true,partner: true,diff --git a/apps/web/lib/api/commissions/metadata-filters.ts b/apps/web/lib/api/commissions/metadata-filters.tsnew file mode 100644index 0000000000..0493ecafe9--- /dev/null+++ b/apps/web/lib/api/commissions/metadata-filters.ts@@ -0,0 +1,130 @@+import { Prisma } from "@prisma/client";+import { DubApiError } from "../errors";++export type CommissionMetadataFilterOp = "equals" | "notEquals";++export type CommissionMetadataFilter = {+ key: string;+ op: CommissionMetadataFilterOp;+ value: string;+};++export type ParsedCommissionMetadataQuery = {+ logic: "AND" | "OR";+ filters: CommissionMetadataFilter[];+};++function mapOperator(operator: string): CommissionMetadataFilterOp {+ switch (operator) {+ case ":":+ case "=":+ return "equals";+ case "!=":+ return "notEquals";+ default:+ throw new DubApiError({+ code: "unprocessable_entity",+ message: "Metadata query only supports `=` and `!=` operators.",+ });+ }+}++function parseCondition(condition: string): CommissionMetadataFilter {+ // Top-level metadata['key'] / metadata["key"] only — nested brackets fail the match.+ const match = condition.match(+ /^metadata\[['"]([A-Za-z0-9_]+)['"]\]\s*(!=|>=|<=|:|=|>|<)\s*(.+)$/,+ );++ if (!match) {+ throw new DubApiError({+ code: "unprocessable_entity",+ message:+ "Invalid metadata query. Use top-level keys only, e.g. `metadata['key']='value'`.",+ });+ }++ const [, key, operator, rawValue] = match;+ const value = rawValue+ .trim()+ .replace(/^['"`]|['"`]$/g, "")+ .replace(/[;\\]|--|\*\/|\/\*/g, "");++ if (!value) {+ throw new DubApiError({+ code: "unprocessable_entity",+ message: "Invalid metadata query: empty filter value.",+ });+ }++ return {+ key,+ op: mapOperator(operator),+ value,+ };+}++export function parseCommissionMetadataQuery(+ query: string | undefined,+): ParsedCommissionMetadataQuery | undefined {+ if (query == null || !query.trim()) {+ return undefined;+ }++ const trimmed = query.trim();+ const hasAnd = /\s+and\s+/i.test(trimmed);+ const hasOr = /\s+or\s+/i.test(trimmed);++ if (hasAnd && hasOr) {+ throw new DubApiError({+ code: "unprocessable_entity",+ message: "Metadata query cannot mix AND and OR.",+ });+ }++ const logic: "AND" | "OR" = hasOr ? "OR" : "AND";+ const conditions = trimmed.split(/\s+(?:and|or)\s+/i);+ const filters: CommissionMetadataFilter[] = [];++ for (const condition of conditions) {+ const trimmedCondition = condition.trim();+ if (!trimmedCondition) {+ continue;+ }+ filters.push(parseCondition(trimmedCondition));+ }++ if (filters.length === 0) {+ throw new DubApiError({+ code: "unprocessable_entity",+ message: "Invalid metadata query.",+ });+ }++ return {+ logic,+ filters,+ };+}++export function buildCommissionMetadataWhere(+ parsed: ParsedCommissionMetadataQuery | undefined,+): Prisma.CommissionWhereInput | undefined {+ if (!parsed) {+ return undefined;+ }++ const clauses: Prisma.CommissionWhereInput[] = parsed.filters.map(+ (filter) => ({+ metadata:+ filter.op === "equals"+ ? { path: `$.${filter.key}`, equals: filter.value }+ : { path: `$.${filter.key}`, not: filter.value },+ }),+ );++ if (clauses.length === 1) {+ return clauses[0];+ }++ return parsed.logic === "OR" ? { OR: clauses } : { AND: clauses };+}diff --git a/apps/web/lib/zod/schemas/commissions.ts b/apps/web/lib/zod/schemas/commissions.tsindex a9fa096481..fc38f969fd 100644--- a/apps/web/lib/zod/schemas/commissions.ts+++ b/apps/web/lib/zod/schemas/commissions.ts@@ -208,6 +208,20 @@ export const getCommissionsQuerySchema = z.optional().describe("The end date of the date range to filter the commissions by."),timezone: z.string().optional(),+ query: z+ .string()+ .max(10000)+ .optional()+ .meta({+ description:+ "Filter by lead or sale event metadata. Top-level keys only.",+ examples: [+ "metadata['key']='value'",+ "metadata['key']!='value'",+ "metadata['key']='value' AND metadata['key2']='value2'",+ "metadata['key']='value' OR metadata['key2']='value2'",+ ],+ }),}).extend({...getCursorPaginationQuerySchema({@@ -652,8 +666,7 @@ const createSaleCommissionSchema = zdata.date != null && "date",data.saleAmount != null && "saleAmount",data.saleEventDate != null && "saleEventDate",- (data.invoiceId != null || data.sale?.invoiceId != null) &&- "invoiceId",+ (data.invoiceId != null || data.sale?.invoiceId != null) && "invoiceId",(data.productId != null || data.sale?.metadata?.productId != null) &&"productId",].filter((field): field is string => Boolean(field));diff --git a/apps/web/lib/zod/schemas/partner-profile.ts b/apps/web/lib/zod/schemas/partner-profile.tsindex 7917adfbda..4ebf624517 100644--- a/apps/web/lib/zod/schemas/partner-profile.ts+++ b/apps/web/lib/zod/schemas/partner-profile.ts@@ -52,6 +52,7 @@ export const getPartnerEarningsQuerySchema = getCommissionsQuerySchema.omit({partnerId: true,sortBy: true,+ query: true,}).extend({interval: z@@ -67,6 +68,7 @@ export const getPartnerEarningsQuerySchema = getCommissionsQuerySchemaexport const getPartnerEarningsCountQuerySchema = getCommissionsCountQuerySchema.omit({partnerId: true,+ query: true,}).extend({interval: zdiff --git a/apps/web/playwright/api/commissions/commissions.spec.ts b/apps/web/playwright/api/commissions/commissions-create.spec.tssimilarity index 100%rename from apps/web/playwright/api/commissions/commissions.spec.tsrename to apps/web/playwright/api/commissions/commissions-create.spec.tsdiff --git a/apps/web/playwright/api/commissions/commissions-list.spec.ts b/apps/web/playwright/api/commissions/commissions-list.spec.tsnew file mode 100644index 0000000000..28046364f5--- /dev/null+++ b/apps/web/playwright/api/commissions/commissions-list.spec.ts@@ -0,0 +1,217 @@+import { createId } from "@/lib/api/create-id";+import { prisma } from "@/lib/prisma";+import type { CommissionResponse } from "@/lib/types";+import { expect } from "@playwright/test";+import { apiError } from "../../utils";+import { test, type ApiClient } from "../fixtures";+import { createPartner } from "../partners/helpers";+import { deleteCommissionPartner } from "./helpers";++test.describe("GET /commissions – metadata query", () => {+ // Shared Prisma seed for this describe; serial so beforeAll runs once per worker group.+ test.describe.configure({ mode: "serial" });++ const seedMetadata: Record<string, string | number | boolean>[] = [+ { plan: "pro", tier: "gold" },+ { plan: "Pro", tier: "silver" },+ { plan: "PRO", seats: 10 },+ { plan: "enterprise", tier: "gold", active: true },+ { plan: "enterprise", seats: 5, active: false },+ { plan: "free", tier: "bronze" },+ { plan: "free", campaign: "Spring" },+ { plan: "starter", seats: 10, active: true },+ { plan: "pro", campaign: "spring" },+ { plan: "enterprise", campaign: "fall", seats: 5 },+ ];++ let partnerId: string | undefined;+ let seeded: {+ id: string;+ metadata: Record<string, string | number | boolean>;+ }[] = [];++ test.beforeAll(async ({ api, program }) => {+ const { status, data } = await createPartner(api, {+ groupId: program.defaultGroupId,+ });+ expect(status).toEqual(201);+ partnerId = data.id;++ const rows = seedMetadata.map((metadata, i) => ({+ id: createId({ prefix: "cm_" }),+ programId: program.id,+ partnerId: data.id,+ type: "custom" as const,+ amount: 0,+ earnings: 100,+ quantity: 1,+ description: `meta-query-${i}`,+ metadata,+ }));++ await prisma.commission.createMany({ data: rows });+ seeded = rows.map((row) => ({+ id: row.id,+ metadata: row.metadata,+ }));+ });++ test.afterAll(async () => {+ await deleteCommissionPartner({ partnerId });+ });++ function matchingIds(+ predicate: (metadata: Record<string, string | number | boolean>) => boolean,+ ) {+ return seeded+ .filter((row) => predicate(row.metadata))+ .map((row) => row.id)+ .sort();+ }++ async function listCommissions(api: ApiClient, query: string) {+ const { status, data } = await api.get<CommissionResponse[]>(+ `/api/commissions?${new URLSearchParams({+ partnerId: partnerId!,+ pageSize: "100",+ query,+ })}`,+ );++ expect(status).toEqual(200);+ return data.map((commission) => commission.id).sort();+ }++ test("filters with =", async ({ api }) => {+ expect(await listCommissions(api, "metadata['plan']='pro'")).toEqual(+ matchingIds((m) => m.plan === "pro"),+ );+ });++ test("filters with : as equals", async ({ api }) => {+ expect(await listCommissions(api, "metadata['plan']:pro")).toEqual(+ matchingIds((m) => m.plan === "pro"),+ );+ });++ test("filters are case-sensitive", async ({ api }) => {+ expect(await listCommissions(api, "metadata['plan']='Pro'")).toEqual(+ matchingIds((m) => m.plan === "Pro"),+ );++ expect(await listCommissions(api, "metadata['plan']='PRO'")).toEqual(+ matchingIds((m) => m.plan === "PRO"),+ );++ expect(await listCommissions(api, "metadata['campaign']='spring'")).toEqual(+ matchingIds((m) => m.campaign === "spring"),+ );++ expect(await listCommissions(api, "metadata['campaign']='Spring'")).toEqual(+ matchingIds((m) => m.campaign === "Spring"),+ );+ });++ test("filters with !=", async ({ api }) => {+ expect(await listCommissions(api, "metadata['plan']!='free'")).toEqual(+ matchingIds((m) => m.plan !== "free"),+ );+ });++ test("filters with AND", async ({ api }) => {+ expect(+ await listCommissions(+ api,+ "metadata['plan']='pro' AND metadata['tier']='gold'",+ ),+ ).toEqual(matchingIds((m) => m.plan === "pro" && m.tier === "gold"));+ });++ test("filters with OR", async ({ api }) => {+ expect(+ await listCommissions(+ api,+ "metadata['plan']='pro' OR metadata['plan']='enterprise'",+ ),+ ).toEqual(matchingIds((m) => m.plan === "pro" || m.plan === "enterprise"));+ });++ test("filters with AND on campaign", async ({ api }) => {+ expect(+ await listCommissions(+ api,+ "metadata['plan']='pro' AND metadata['campaign']='spring'",+ ),+ ).toEqual(matchingIds((m) => m.plan === "pro" && m.campaign === "spring"));+ });++ test("filters with OR on campaign", async ({ api }) => {+ expect(+ await listCommissions(+ api,+ "metadata['campaign']='spring' OR metadata['campaign']='fall'",+ ),+ ).toEqual(+ matchingIds((m) => m.campaign === "spring" || m.campaign === "fall"),+ );+ });++ test("does not match numeric metadata values stored as numbers", async ({+ api,+ }) => {+ expect(await listCommissions(api, "metadata['seats']='10'")).toEqual([]);+ expect(await listCommissions(api, "metadata['seats']='5'")).toEqual([]);+ });++ test("does not match boolean metadata values stored as booleans", async ({+ api,+ }) => {+ expect(await listCommissions(api, "metadata['active']='true'")).toEqual([]);+ expect(await listCommissions(api, "metadata['active']='false'")).toEqual(+ [],+ );+ });++ const invalidQueryCases = [+ {+ name: "rejects nested metadata keys",+ query: "metadata['a']['b']='value'",+ message:+ "Invalid metadata query. Use top-level keys only, e.g. `metadata['key']='value'`.",+ },+ {+ name: "rejects mixed AND and OR",+ query: "metadata['a']='1' AND metadata['b']='2' OR metadata['c']='3'",+ message: "Metadata query cannot mix AND and OR.",+ },+ {+ name: "rejects unsupported comparison operators",+ query: "metadata['seats']>5",+ message: "Metadata query only supports `=` and `!=` operators.",+ },+ {+ name: "rejects non-metadata fields",+ query: "status:active",+ message:+ "Invalid metadata query. Use top-level keys only, e.g. `metadata['key']='value'`.",+ },+ ];++ for (const { name, query, message } of invalidQueryCases) {+ test(name, async ({ api }) => {+ expect(+ await api.get(+ `/api/commissions?${new URLSearchParams({+ partnerId: partnerId!,+ query,+ })}`,+ ),+ ).toEqual(+ apiError({+ code: "unprocessable_entity",+ message,+ }),+ );+ });+ }+});diff --git a/apps/web/tests/commissions/metadata-filters.test.ts b/apps/web/tests/commissions/metadata-filters.test.tsnew file mode 100644index 0000000000..e34d7feb6c--- /dev/null+++ b/apps/web/tests/commissions/metadata-filters.test.ts@@ -0,0 +1,189 @@+import {+ buildCommissionMetadataWhere,+ parseCommissionMetadataQuery,+} from "@/lib/api/commissions/metadata-filters";+import { DubApiError } from "@/lib/api/errors";+import { describe, expect, it, vi } from "vitest";++vi.mock("server-only", () => ({}));++describe("parseCommissionMetadataQuery", () => {+ it("returns undefined for absent, empty, or whitespace-only query", () => {+ expect(parseCommissionMetadataQuery(undefined)).toBeUndefined();+ expect(parseCommissionMetadataQuery("")).toBeUndefined();+ expect(parseCommissionMetadataQuery(" ")).toBeUndefined();+ });++ it("parses = operator", () => {+ expect(parseCommissionMetadataQuery("metadata['plan']='pro'")).toEqual({+ logic: "AND",+ filters: [{ key: "plan", op: "equals", value: "pro" }],+ });+ });++ it("parses : as equals", () => {+ expect(parseCommissionMetadataQuery("metadata['plan']:pro")).toEqual({+ logic: "AND",+ filters: [{ key: "plan", op: "equals", value: "pro" }],+ });+ });++ it("parses != operator", () => {+ expect(parseCommissionMetadataQuery("metadata['plan']!='free'")).toEqual({+ logic: "AND",+ filters: [{ key: "plan", op: "notEquals", value: "free" }],+ });+ });++ it("parses AND connective", () => {+ expect(+ parseCommissionMetadataQuery(+ "metadata['plan']='pro' AND metadata['tier']='gold'",+ ),+ ).toEqual({+ logic: "AND",+ filters: [+ { key: "plan", op: "equals", value: "pro" },+ { key: "tier", op: "equals", value: "gold" },+ ],+ });+ });++ it("parses OR connective (case-insensitive)", () => {+ expect(+ parseCommissionMetadataQuery(+ "metadata['plan']='pro' or metadata['plan']='enterprise'",+ ),+ ).toEqual({+ logic: "OR",+ filters: [+ { key: "plan", op: "equals", value: "pro" },+ { key: "plan", op: "equals", value: "enterprise" },+ ],+ });+ });++ it("rejects nested metadata keys", () => {+ expect(() =>+ parseCommissionMetadataQuery("metadata['a']['b']='value'"),+ ).toThrow(DubApiError);+ try {+ parseCommissionMetadataQuery("metadata['a']['b']='value'");+ } catch (error) {+ expect(error).toBeInstanceOf(DubApiError);+ expect((error as DubApiError).code).toBe("unprocessable_entity");+ }+ });++ it("rejects dotted metadata keys", () => {+ expect(() =>+ parseCommissionMetadataQuery("metadata['a.b']='value'"),+ ).toThrow(DubApiError);+ });++ it("rejects mixed AND and OR", () => {+ expect(() =>+ parseCommissionMetadataQuery(+ "metadata['a']='1' AND metadata['b']='2' OR metadata['c']='3'",+ ),+ ).toThrow(DubApiError);+ try {+ parseCommissionMetadataQuery(+ "metadata['a']='1' AND metadata['b']='2' OR metadata['c']='3'",+ );+ } catch (error) {+ expect((error as DubApiError).message).toBe(+ "Metadata query cannot mix AND and OR.",+ );+ }+ });++ it("rejects unsupported comparison operators", () => {+ for (const query of [+ "metadata['seats']>5",+ "metadata['seats']<5",+ "metadata['seats']>=5",+ "metadata['seats']<=5",+ ]) {+ expect(() => parseCommissionMetadataQuery(query)).toThrow(DubApiError);+ try {+ parseCommissionMetadataQuery(query);+ } catch (error) {+ expect((error as DubApiError).message).toBe(+ "Metadata query only supports `=` and `!=` operators.",+ );+ }+ }+ });++ it("rejects non-metadata fields and junk", () => {+ expect(() => parseCommissionMetadataQuery("status:active")).toThrow(+ DubApiError,+ );+ expect(() => parseCommissionMetadataQuery("not-a-query")).toThrow(+ DubApiError,+ );+ });+});++describe("buildCommissionMetadataWhere", () => {+ it("returns undefined for undefined input", () => {+ expect(buildCommissionMetadataWhere(undefined)).toBeUndefined();+ });++ it("builds a single equals clause", () => {+ expect(+ buildCommissionMetadataWhere({+ logic: "AND",+ filters: [{ key: "plan", op: "equals", value: "pro" }],+ }),+ ).toEqual({+ metadata: { path: "$.plan", equals: "pro" },+ });+ });++ it("builds a single notEquals clause", () => {+ expect(+ buildCommissionMetadataWhere({+ logic: "AND",+ filters: [{ key: "plan", op: "notEquals", value: "free" }],+ }),+ ).toEqual({+ metadata: { path: "$.plan", not: "free" },+ });+ });++ it("builds AND of multiple clauses", () => {+ expect(+ buildCommissionMetadataWhere({+ logic: "AND",+ filters: [+ { key: "plan", op: "equals", value: "pro" },+ { key: "tier", op: "equals", value: "gold" },+ ],+ }),+ ).toEqual({+ AND: [+ { metadata: { path: "$.plan", equals: "pro" } },+ { metadata: { path: "$.tier", equals: "gold" } },+ ],+ });+ });++ it("builds OR of multiple clauses", () => {+ expect(+ buildCommissionMetadataWhere({+ logic: "OR",+ filters: [+ { key: "plan", op: "equals", value: "pro" },+ { key: "plan", op: "equals", value: "enterprise" },+ ],+ }),+ ).toEqual({+ OR: [+ { metadata: { path: "$.plan", equals: "pro" } },+ { metadata: { path: "$.plan", equals: "enterprise" } },+ ],+ });+ });+});