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 OpenAPI description, improve validateBounty error messages

Steven Tey2b6c3ea65821
diff --git a/apps/web/app/(ee)/api/bounties/route.ts b/apps/web/app/(ee)/api/bounties/route.ts
index dbbce7d699..aa8ae62f83 100644
--- a/apps/web/app/(ee)/api/bounties/route.ts
+++ b/apps/web/app/(ee)/api/bounties/route.ts
@@ -225,7 +225,7 @@ export const POST = withWorkspace(
// startsAt is only stored for absolute bounties (defaulting to now when
// omitted); relative bounties start when a partner joins, so it stays null.
startsAt =
- startMode === BountyStartMode.absolute ? startsAt || new Date() : null;
+ startMode === BountyStartMode.relative ? null : startsAt || new Date();
const bounty = await prisma.$transaction(async (tx) => {
let workflow: Workflow | null = null;
@@ -301,12 +301,12 @@ export const POST = withWorkspace(
const shouldScheduleDraftSubmissions =
bounty.type === "performance" &&
bounty.performanceScope === "lifetime" &&
- bounty.startMode === BountyStartMode.absolute;
+ bounty.startMode !== BountyStartMode.relative;
const shouldSchedulePartnerNotifications =
sendNotificationEmails &&
canSendEmailCampaigns &&
- bounty.startMode === BountyStartMode.absolute;
+ bounty.startMode !== BountyStartMode.relative;
waitUntil(
Promise.allSettled([
diff --git a/apps/web/lib/bounty/api/validate-bounty.ts b/apps/web/lib/bounty/api/validate-bounty.ts
index 94250fbce0..ff2315695e 100644
--- a/apps/web/lib/bounty/api/validate-bounty.ts
+++ b/apps/web/lib/bounty/api/validate-bounty.ts
@@ -23,7 +23,7 @@ export function validateBounty({
if (startsAt != null) {
throw new DubApiError({
message:
- "startsAt is not supported when the bounty starts when a partner joins. It must be null for relative bounties.",
+ "`startsAt` is not supported when the `startMode` is `relative`.",
code: "bad_request",
});
}
@@ -34,8 +34,7 @@ export function validateBounty({
if (endsAt && endsAfterDays) {
throw new DubApiError({
- message:
- "Bounty cannot have both an end date (endsAt) and endsAfterDays.",
+ message: "Bounties cannot have both `endsAt` and `endsAfterDays`.",
code: "bad_request",
});
}
@@ -43,7 +42,7 @@ export function validateBounty({
if (startMode === BountyStartMode.absolute && endsAfterDays) {
throw new DubApiError({
message:
- "endsAfterDays is only supported when the bounty starts when a partner joins.",
+ "`endsAfterDays` is only supported when the `startMode` is `relative`.",
code: "bad_request",
});
}
@@ -51,7 +50,7 @@ export function validateBounty({
if (endsAt && startsAt && endsAt < startsAt) {
throw new DubApiError({
message:
- "Bounty end date (endsAt) must be on or after start date (startsAt).",
+ "The bounty's end date (`endsAt`) must be on or after the start date (`startsAt`).",
code: "bad_request",
});
}
@@ -59,24 +58,21 @@ export function validateBounty({
if (submissionsOpenAt) {
if (!endsAt) {
throw new DubApiError({
- message:
- "An end date is required to determine when the submission window opens.",
+ message: "`endsAt` is required when `submissionsOpenAt` is set.",
code: "bad_request",
});
}
if (startsAt && submissionsOpenAt < startsAt) {
throw new DubApiError({
- message:
- "Bounty submissions open date (submissionsOpenAt) must be on or after start date (startsAt).",
+ message: "`submissionsOpenAt` must be on or after `startsAt`.",
code: "bad_request",
});
}
if (submissionsOpenAt > endsAt) {
throw new DubApiError({
- message:
- "Bounty submissions open date (submissionsOpenAt) must be on or before end date (endsAt).",
+ message: "`submissionsOpenAt` must be on or before `endsAt`.",
code: "bad_request",
});
}
@@ -86,7 +82,7 @@ export function validateBounty({
if (type === "performance") {
throw new DubApiError({
code: "bad_request",
- message: "Reward amount is required for performance bounties.",
+ message: "`rewardAmount` is required for `performance` bounties.",
});
}
@@ -94,7 +90,7 @@ export function validateBounty({
throw new DubApiError({
code: "bad_request",
message:
- "For submission bounties, either reward amount or reward description is required.",
+ "For `submission` bounties, either `rewardAmount` or `rewardDescription` is required.",
});
}
}
@@ -102,7 +98,7 @@ export function validateBounty({
if (!performanceScope && type === "performance") {
throw new DubApiError({
code: "bad_request",
- message: "performanceScope must be set for performance bounties.",
+ message: "`performanceScope` must be set for `performance` bounties.",
});
}
@@ -113,7 +109,7 @@ export function validateBounty({
throw new DubApiError({
code: "bad_request",
message:
- "Lifetime stats are not supported when the bounty starts when a partner joins.",
+ "`lifetime` performance scope is not supported when the `startMode` is `relative`.",
});
}
@@ -122,14 +118,15 @@ export function validateBounty({
if (submissionFrequency && maxSubmissions == null) {
throw new DubApiError({
code: "bad_request",
- message: "maxSubmissions is required when submissionFrequency is set.",
+ message:
+ "`maxSubmissions` is required when `submissionFrequency` is set.",
});
}
if (submissionFrequency && !endsAt && !endsAfterDays) {
throw new DubApiError({
code: "bad_request",
- message: "An end date is required when submissionFrequency is set.",
+ message: "`endsAt` is required when `submissionFrequency` is set.",
});
}
}
diff --git a/apps/web/lib/zod/schemas/bounties.ts b/apps/web/lib/zod/schemas/bounties.ts
index d4601bb460..e3f0b32b14 100644
--- a/apps/web/lib/zod/schemas/bounties.ts
+++ b/apps/web/lib/zod/schemas/bounties.ts
@@ -85,7 +85,10 @@ export const createBountySchema = z.object({
.string()
.trim()
.max(100, "Name must be less than 100 characters")
- .nullish(),
+ .nullish()
+ .describe(
+ "The name of the bounty. E.g.: `June Product Launch Promo`. Only applicable for `submission` bounties.",
+ ),
description: z
.string()
.trim()
@@ -93,39 +96,118 @@ export const createBountySchema = z.object({
BOUNTY_DESCRIPTION_MAX_LENGTH,
`Description must be less than ${BOUNTY_DESCRIPTION_MAX_LENGTH} characters`,
)
- .nullish(),
- type: z.enum(BountyType),
- startsAt: parseDateSchema.nullish(),
- endsAt: parseDateSchema.nullish(),
- submissionsOpenAt: parseDateSchema.nullish(),
- submissionFrequency: z.enum(BountySubmissionFrequency).nullish(),
+ .nullish()
+ .describe(
+ "The description of the bounty. Use this field to outline the rules and requirements for the bounty.",
+ ),
+ type: z
+ .enum(BountyType)
+ .describe(
+ [
+ "The type of bounty.",
+ "`performance`: Bounties that are awarded based on partner performance (leads, conversions, revenue, commissions).",
+ "`submission`: Bounties that are awarded based on partner submissions (can be an arbitrary submission or a social content submission).",
+ ].join("\n"),
+ ),
+ startMode: z
+ .enum(BountyStartMode)
+ .optional()
+ .describe(
+ [
+ "How the bounty's start date is determined.",
+ "`absolute`: Bounty starts at a specific date and time.",
+ "`relative`: Bounty starts when a partner joins the program.",
+ ].join("\n"),
+ ),
+ startsAt: parseDateSchema
+ .nullish()
+ .describe(
+ "The date and time the bounty starts. Only applicable when `startMode` is absolute.",
+ ),
+ endsAt: parseDateSchema
+ .nullish()
+ .describe(
+ "The date and time the bounty ends. Only applicable when `startMode` is absolute.",
+ ),
+ endsAfterDays: z
+ .number()
+ .int()
+ .positive()
+ .nullish()
+ .describe(
+ "How long after a partner joins the program is the bounty open for. Only applicable when `startMode` is relative.",
+ ),
+ submissionsOpenAt: parseDateSchema
+ .nullish()
+ .describe(
+ "The date and time after which partners can finalize their bounty submissions. Only applicable for `submission` bounties.",
+ ),
maxSubmissions: z
.number()
.int()
- .min(2, "Total submissions allowed must be at least 2")
+ .min(2, "If `maxSubmissions` is set, it must be at least 2")
.max(BOUNTY_MAX_SUBMISSIONS)
- .nullish(),
+ .nullish()
+ .describe(
+ "The maximum number of submissions a partner can enter. Only applicable for `submission` bounties.",
+ ),
+ submissionFrequency: z
+ .enum(BountySubmissionFrequency)
+ .nullish()
+ .describe(
+ [
+ "How often partners can submit their bounty submissions.",
+ "`daily`: Partners can submit their bounty submissions once per day.",
+ "`weekly`: Partners can submit their bounty submissions once per week.",
+ "`monthly`: Partners can submit their bounty submissions once per month.",
+ "Only applicable for bounties that have `maxSubmissions` set.",
+ ].join("\n"),
+ ),
rewardAmount: z
.number()
.positive()
.min(1, "Reward amount must be greater than 1")
- .nullable(),
+ .nullable()
+ .describe("The reward amount for the bounty in USD cents."),
rewardDescription: z
.string()
.trim()
.max(100, "Reward description must be less than 100 characters")
.transform((v) => (v === "" ? null : v))
- .nullish(),
- submissionRequirements: submissionRequirementsSchema.nullish(),
- groupIds: z.array(z.string()).nullable(),
- performanceCondition: awardBountyConditionSchema.nullish(),
- performanceScope: z.enum(BountyPerformanceScope).nullish(),
- sendNotificationEmails: z.boolean().optional(),
- startMode: z
- .enum(BountyStartMode)
+ .nullish()
+ .describe(
+ "The reward description for `submission` bounties if a custom reward amount is set",
+ ),
+ performanceCondition: awardBountyConditionSchema
+ .nullish()
+ .describe(
+ "The condition that must be met for a `performance` bounty to be awarded. Only applicable for `performance` bounties.",
+ ),
+ performanceScope: z
+ .enum(BountyPerformanceScope)
+ .nullish()
+ .describe(
+ [
+ "The scpoe of the performance criteria:",
+ "`lifetime`: Bounty takes into account all-time performance data",
+ "`new`: Bounty only counts performance data after the bounty starts",
+ ].join("\n"),
+ ),
+ submissionRequirements: submissionRequirementsSchema
+ .nullish()
+ .describe(
+ "The requirements that must be met for a bounty submission to be finalized. Only applicable for `submission` bounties.",
+ ),
+ groupIds: z
+ .array(z.string())
+ .nullable()
+ .describe("The IDs of the partner groups that this bounty is available to"),
+ sendNotificationEmails: z
+ .boolean()
.optional()
- .default(BountyStartMode.absolute),
- endsAfterDays: z.number().int().positive().nullish(),
+ .describe(
+ "Whether to send notification emails to partners when the bounty is created.",
+ ),
});
export const updateBountySchema = createBountySchema
diff --git a/apps/web/tests/bounties/index.test.ts b/apps/web/tests/bounties/index.test.ts
index 5c6cb5057b..c0213ae482 100644
--- a/apps/web/tests/bounties/index.test.ts
+++ b/apps/web/tests/bounties/index.test.ts
@@ -368,7 +368,7 @@ describe.sequential(
expect(data).toMatchObject({
error: {
message:
- "maxSubmissions is required when submissionFrequency is set.",
+ "`maxSubmissions` is required when `submissionFrequency` is set.",
},
});
});
@@ -387,7 +387,7 @@ describe.sequential(
expect(status).toEqual(400);
expect(data).toMatchObject({
error: {
- message: "An end date is required when submissionFrequency is set.",
+ message: "`endsAt` is required when `submissionFrequency` is set.",
},
});
});
@@ -432,8 +432,7 @@ describe.sequential(
expect(status).toEqual(400);
expect(data).toMatchObject({
error: {
- message:
- "An end date is required to determine when the submission window opens.",
+ message: "`endsAt` is required when `submissionsOpenAt` is set.",
},
});
});
@@ -449,8 +448,7 @@ describe.sequential(
expect(status).toEqual(400);
expect(data).toMatchObject({
error: {
- message:
- "Bounty submissions open date (submissionsOpenAt) must be on or after start date (startsAt).",
+ message: "`submissionsOpenAt` must be on or after `startsAt`.",
},
});
});
@@ -466,8 +464,7 @@ describe.sequential(
expect(status).toEqual(400);
expect(data).toMatchObject({
error: {
- message:
- "Bounty submissions open date (submissionsOpenAt) must be on or before end date (endsAt).",
+ message: "`submissionsOpenAt` must be on or before `endsAt`.",
},
});
});
@@ -541,7 +538,7 @@ describe.sequential(
expect(status).toEqual(400);
expect(data).toMatchObject({
error: {
- message: "An end date is required when submissionFrequency is set.",
+ message: "`endsAt` is required when `submissionFrequency` is set.",
},
});
});
@@ -557,8 +554,7 @@ describe.sequential(
expect(status).toEqual(400);
expect(data).toMatchObject({
error: {
- message:
- "An end date is required to determine when the submission window opens.",
+ message: "`endsAt` is required when `submissionsOpenAt` is set.",
},
});
});
@@ -652,14 +648,10 @@ describe.sequential("/bounties - relative start mode", async () => {
expect(data).toMatchObject({
error: {
message:
- "startsAt is not supported when the bounty starts when a partner joins. It must be null for relative bounties.",
+ "`startsAt` is not supported when the `startMode` is `relative`.",
code: "bad_request",
},
});
-
- onTestFinished(async () => {
- await h.deleteBounty(bounty.id);
- });
});
test("POST /bounties - both endsAt and endsAfterDays is rejected", async () => {
@@ -675,8 +667,7 @@ describe.sequential("/bounties - relative start mode", async () => {
expect(status).toEqual(400);
expect(data).toMatchObject({
error: {
- message:
- "Bounty cannot have both an end date (endsAt) and endsAfterDays.",
+ message: "Bounties cannot have both `endsAt` and `endsAfterDays`.",
code: "bad_request",
},
});