Partner Program Management | blade47/dub Wiki | doc0

Public

Partner Program Management | blade47/dub Wiki | doc0

const { canManageProgram, canMessagePartners } = getPlanCapabilities(
  workspace.plan,
);
 
if (
  !canManageProgram ||
  isLegacyBusinessPlan({
    plan: workspace.plan,
    partnersLimit: workspace.partnersLimit,
  })
) {
  throw new Error(
    "Your current plan does not have access to create a partner program. Please upgrade to a higher plan to proceed.",
  );
}

Parameter	Type / Source	Purpose
`workspace`	`Pick<Project, "id" \| "slug" \| "logo" \| "name" \| "plan" \| "partnersLimit" \| "trialEndsAt" \| "store" \| "webhookEnabled" \| "invoicePrefix">`	Workspace context supplying id, slug, plan, and limits.
`user`	`Pick<User, "id" \| "email">`	Authenticated user initializing the program.
`isProgramOnboarding`	`boolean`	Optional flag indicating initial setup flow context.
`store.programOnboarding`	`Record<string, any>`	JSON store blob containing form inputs parsed by `programDataSchema`.

Endpoint Method & Path	Validation Schema	Purpose
`GET /api/partners/links`	`retrievePartnerLinksSchemaInternal`	Retrieves existing tracking links for an enrolled partner, optionally including reward associations.
`POST /api/partners/links`	`createPartnerLinkSchemaInternal`	Generates a new tracking link for a partner, applying group UTM templates, default URLs, and optional reward overrides.

Background Task	Trigger / Handler Function	Purpose
Program Notification	`notifyProgramApplication`	Sends application notifications to program administrators.
Auto-Approval	`autoApprovePartnerJob`	Automatically approves the partner enrollment if `autoApprovePartnersEnabledAt` is active on the group.
Webhook Dispatch	`sendWorkspaceWebhook`	Fires a `partner.application_submitted` workspace webhook payload validated against `partnerApplicationWebhookSchema`.
Fraud Detection	`detectAndRecordFraudApplication`	Evaluates submission context to detect and log fraudulent application behavior.
Event Tracking	`markApplicationEventSubmitted`	Marks the application lifecycle event as submitted for the given enrollment.
Search Index Sync	`queuePartnerSearchSync`	Queues search indexing updates for the newly created program enrollment ID.

Tab ID / Status	Label	Icon Component	Associated Route
`ProgramApplicationStatus.pending`	Pending	`CircleHalfDottedClock`	`/${slug}/program/partners/applications`
`ProgramApplicationStatus.approved`	Approved	`CircleCheck`	Derived tab interface
`ProgramApplicationStatus.rejected`	Rejected	`UserXmark`	Derived tab interface

Interface / Endpoint	Input Validation Schema	Required Roles	Target Handler Function
`approveProgramApplicationAction` (Server Action)	`inputSchema` (`partnerId`, `groupId`, `workspaceId`)	`owner`, `member`	`approveProgramApplication`
`POST /api/program-applications/approve` (REST API)	`approveProgramApplicationSchema` (`partnerId`, `groupId`)	`owner`, `member`	`approveProgramApplication`

export const GET = withWorkspace(
  async ({ workspace, searchParams }) => {
    const programId = getDefaultProgramIdOrThrow(workspace);
    const filterOverrides = parsePartnerFilterParams(searchParams);
    const paramsToParse = {
      ...searchParams,
      ...(filterOverrides.partnerTagId && {
        partnerTagId: filterOverrides.partnerTagId,
      }),
      ...(filterOverrides.groupId !== undefined && {
        groupId: filterOverrides.groupId,
      }),
      ...(filterOverrides.country !== undefined && {
        country: filterOverrides.country,
      }),
    };
    const { sortBy: sortByWithOldFields, ...parsedParams } =
      getPartnersRouteQuerySchema.parse(paramsToParse);
 
    const sortBy =
      {
        clicks: "totalClicks",
        leads: "totalLeads",
        conversions: "totalConversions",
        sales: "totalSaleAmount",
        saleAmount: "totalSaleAmount",
        totalSales: "totalSaleAmount",
      }[sortByWithOldFields] || sortByWithOldFields;
 
    const partners = await getPartners({
      ...parsedParams,
      sortBy,
      programId,
    });
    // ...
  },
  {
    requiredPlan: ["business", "advanced", "enterprise"],
  },
);

export const POST = withWorkspace(
  async ({ workspace, req, session }) => {
    const programId = getDefaultProgramIdOrThrow(workspace);
 
    const {
      partnerId,
      tenantId,
      url,
      key,
      linkProps,
      clickRewardId,
      leadRewardId,
      saleRewardId,
      discountId,
    } = createPartnerLinkSchemaInternal.parse(await parseRequestBody(req));
 
    const program = await getProgramOrThrow({
      workspaceId: workspace.id,
      programId,
    });
 
    if (!program.domain || !program.url) {
      throw new DubApiError({
        code: "bad_request",
        message:
          "You need to set a domain and url for this program before creating a link.",
      });
    }
    // ...
  },
  {
    requiredPlan: ["business", "advanced", "enterprise"],
    requiredRoles: ["owner", "member"],
  },
);

export default function ProgramPartnerLayout({
  children,
}: {
  children: ReactNode;
}) {
  const { slug: workspaceSlug } = useWorkspace();
  const router = useRouter();
  const pathname = usePathname();
  const searchParams = useSearchParams();
 
  const params = useParams() as { slug: string; partnerId: string };
  const { partner, error: partnerError } = usePartner({
    partnerId: params.partnerId,
  });
 
  if (partnerError && partnerError.status === 404) {
    redirect(`/${workspaceSlug}/program/partners`);
  }
 
  const switchToPartner = (newPartnerId: string) => {
    if (params.partnerId === newPartnerId) return;
    const url = `${pathname.replace(`/partners/${params.partnerId}`, `/partners/${newPartnerId}`)}?${searchParams.toString()}`;
    router.push(url);
  };
  // ...
}

  const selectedProgram = useMemo(() => {
    const program = programEnrollments?.find(
      (programEnrollment) => programEnrollment.program.slug === programSlug,
    );
 
    return programSlug && program
      ? {
          ...program.program,
          logo:
            program.program.logo || `${OG_AVATAR_URL}${program.program.name}`,
          status: program.status,
        }
      : undefined;
  }, [programSlug, programEnrollments]);

  const href = useCallback(
    (slug: string) =>
      selectedProgram
        ? `${pathname.replace(selectedProgram.slug, slug)}${searchParamsString.length > 0 ? `?${searchParamsString}` : ""}`
        : `/programs/${slug}`,
    [pathname, selectedProgram],
  );