Embeddable Referrals

Copyclass ReferralsEmbedToken {
  async create(props: ReferralsEmbedTokenProps) {
    const publicToken = createId({
      prefix: EMBED_PUBLIC_TOKEN_PREFIX,
    });
 
    await redis.set(publicToken, JSON.stringify(props), {
      ex: EMBED_PUBLIC_TOKEN_EXPIRY,
      nx: true,
    });
 
    return {
      publicToken,
      expires: new Date(Date.now() + EMBED_PUBLIC_TOKEN_EXPIRY * 1000),
    };
  }
 
  async get(token: string) {
    return await redis.get<ReferralsEmbedTokenProps>(token);
  }
}

Copy// POST /api/tokens/embed/referrals - create a new embed token for the given partner/tenant
export const POST = withWorkspace(
  async ({ workspace, req, session }) => {
    const programId = getDefaultProgramIdOrThrow(workspace);
 
    const {
      partnerId,
      tenantId,
      partner: partnerProps,
    } = createReferralsEmbedTokenSchema.parse(await parseRequestBody(req));
 
    const finalTenantId =
      tenantId || partnerProps?.tenantId || partnerProps?.linkProps?.tenantId;
 
    let programEnrollment: Pick<ProgramEnrollment, "partnerId"> | null = null;
 
    // find the program enrollment for the given partnerId or tenantId
    if (partnerId || finalTenantId) {
      programEnrollment = await prisma.programEnrollment.findUnique({
        where: partnerId
          ? { partnerId_programId: { partnerId, programId } }
          : { tenantId_programId: { tenantId: finalTenantId!, programId } },
        select: {
          partnerId: true,
        },
      });
    }
 
    // if there is no programEnrollment associated with the partnerId or tenantId, and partnerProps are provided
    // check if the partner exists based on the email – if not, create them, if yes, enroll them
    if (!programEnrollment && partnerProps) {
      const program = await prisma.program.findUniqueOrThrow({
        where: {
          id: programId,
        },
        select: {
          id: true,
          workspaceId: true,
          defaultFolderId: true,
          domain: true,
          url: true,
          defaultGroupId: true,
        },
      });
 
      const partner = await prisma.partner.findUnique({
        where: {
          email: partnerProps.email,
        },
        include: {
          programs: {
            where: {
              programId,
            },
          },
        },
      });
 
      // partner does not exist, we need to create them OR
      // partner exists but is not enrolled in the program, we need to enroll them
      if (!partner || partner.programs.length === 0) {
        const { linkProps: link, ...partner } = partnerProps;
 
        const enrolledPartner = await createAndEnrollPartner({
          workspace,
          program,
          partner: {
            ...partner,
            ...(finalTenantId && { tenantId: finalTenantId }),
          },
          link: {
            ...link,
            ...(finalTenantId && { tenantId: finalTenantId }),
          },
          userId: session.user.id,
        });
 
        programEnrollment = {
          partnerId: enrolledPartner.id,
        };

Copyexport const GET = withSession(async ({ session }) => {
  const user = await prisma.user.findUniqueOrThrow({
    where: {
      id: session.user.id,
    },
    include: {
      partners: {
        include: {
          partner: {
            include: {
              programs: true,
            },
          },
        },
      },
      projects: {
        where: {
          project: {
            plan: {
              not: "free",
            },
          },
        },
      },
    },
  });
  const paidWorkspaces = user.projects.map((project) => project);
 
  // for free users, need to do some extra checks
  if (paidWorkspaces.length === 0) {
    // for partners with free workspaces, they are only eligible if they have a good reputation
    const programEnrollments = user.partners[0]
      ? user.partners[0].partner.programs
      : [];
    if (
      programEnrollments.length > 0 &&
      !(
        partnerHasEarnedCommissions(
          programEnrollments as ProgramEnrollmentsForDiscoverability,
        ) && partnerIsNotBanned(programEnrollments)
      )
    ) {
      return NextResponse.json({ publicToken: null });
    }
 
    // for regular free users, don't allow them to join the referral program if they've just joined (within the last 30 days)
    if (user.createdAt > new Date(Date.now() - 30 * 24 * 60 * 60 * 1000)) {
      return NextResponse.json({ publicToken: null });
    }
  }
 
  const { publicToken } = await dub.embedTokens.referrals({
    tenantId: session.user.id,
    partner: {
      name: session.user.name || session.user.email,
      email: session.user.email,
      image: session.user.image || null,
      tenantId: session.user.id,
      groupId: "grp_1K2QJWRQ917XX2YR5VHQ1RRC5", // User Referrals group
    },
  });
 
  return NextResponse.json({ publicToken });
});

Copyexport const createReferralsEmbedToken: ZodOpenApiOperationObject = {
  operationId: "createReferralsEmbedToken",
  "x-speakeasy-name-override": "referrals",
  summary: "Create a referrals embed token",
  description:
    "Create a referrals embed token for the given partner/tenant. The endpoint first attempts to locate an existing enrollment using the provided tenantId. If no enrollment is found, it resolves the partner by email and creates a new enrollment as needed. This results in an upsert-style flow that guarantees a valid enrollment and returns a usable embed token.",
  requestBody: {
    content: {
      "application/json": {
        schema: createReferralsEmbedTokenSchema,
      },
    },
  },
  responses: {
    "201": {
      description: "The created public embed token.",
      content: {
        "application/json": {
          schema: ReferralsEmbedTokenSchema,
        },
      },
    },
    ...openApiErrorResponses,
  },
  tags: ["Embed Tokens"],
  security: [{ token: [] }],
};

Copyexport const withReferralsEmbedToken = (
  handler: WithReferralsEmbedTokenHandler,
) => {
  return withAxiom(
    async (
      req,
      { params: initialParams }: { params: Promise<Record<string, string>> },
    ) => {
      const params = (await initialParams) || {};
      const requestHeaders = await headers();
      let responseHeaders = new Headers();
 
      try {
        const rateLimit = 60;
        const searchParams = getSearchParams(req.url);
        const embedToken = requestHeaders.get("Authorization")?.split(" ")[1];
 
        if (!embedToken) {
          throw new DubApiError({
            code: "unauthorized",
            message: "Embed public token not found in the request.",
          });
        }
 
        const { programId, partnerId } =
          (await referralsEmbedToken.get(embedToken)) ?? {};
 
        if (!programId || !partnerId) {
          throw new DubApiError({
            code: "unauthorized",
            message: "Invalid embed public token.",
          });
        }

Copyconst { success, limit, reset, remaining } = await ratelimit(
  rateLimit,
  "1 m",
).limit(embedToken);
 
responseHeaders.set("Retry-After", reset.toString());
responseHeaders.set("X-RateLimit-Limit", limit.toString());
responseHeaders.set("X-RateLimit-Remaining", remaining.toString());
responseHeaders.set("X-RateLimit-Reset", reset.toString());
 
if (!success) {
  throw new DubApiError({
    code: "rate_limit_exceeded",
    message: "Too many requests.",
  });
}
 

Copyconst { program, links, partnerGroup, ...programEnrollment } =
  await prisma.programEnrollment.findUniqueOrThrow({
    where: {
      partnerId_programId: {
        partnerId,
        programId,
      },
    },
    include: {
      links: {
        orderBy: [
          {
            saleAmount: "desc",
          },
          {
            leads: "desc",
          },
          {
            clicks: "desc",
          },
        ],
      },
      program: true,
      partnerGroup: true,
    },
  });
 
if (!partnerGroup) {
  throw new DubApiError({
    code: "forbidden",
    message:
      "You’re not part of any group yet. Please reach out to the program owner to be added.",
  });
}
 
return await handler({
  req,
  params,
  searchParams,
  program,
  programEnrollment,
  group: partnerGroup as PartnerGroupProps,
  links,
  embedToken,
});

Copy// GET /api/embed/referrals/token - get the referrals embed token
export const GET = withReferralsEmbedToken(async ({ embedToken }) => {
  return NextResponse.json(embedToken);
});

Copyimport { NextRequest, NextResponse } from "next/server";
import { parse } from "./utils/parse";
 
export function EmbedMiddleware(req: NextRequest) {
  const { path, searchParamsObj, fullPath } = parse(req);
 
  if (path.startsWith("/embed/support-chat")) {
    return NextResponse.rewrite(new URL(`/app.dub.co${fullPath}`, req.url));
  }
 
  if (searchParamsObj.token) {
    return NextResponse.rewrite(new URL(`/app.dub.co${fullPath}`, req.url));
  }
 
  // TODO: Show token expiry page
  return NextResponse.redirect(new URL("/", req.url));
}

Copy"use client";
 
import { DubEmbedOptions, init } from "@dub/embed-core";
import { HTMLProps, memo, useEffect, useId, useRef } from "react";
 
type Options = Omit<DubEmbedOptions, "token">;
 
type DubEmbedProps = {
  token: DubEmbedOptions["token"];
  data: DubEmbedOptions["data"];
  options?: Options;
} & HTMLProps<HTMLDivElement>;
 
export const DubEmbed = memo(
  ({ token, data, options, ...rest }: DubEmbedProps) => (
    <DubEmbedInner options={{ ...options, token, data }} {...rest} />
  ),
);

Copyfunction DubEmbedInner({
  options,
  ...rest
}: { options: DubEmbedOptions } & HTMLProps<HTMLDivElement>) {
  const id = useId();
  const rootRef = useRef<HTMLDivElement>(null);
 
  useEffect(() => {
    if (!rootRef.current) return;
 
    const { destroy } =
      init({
        root: rootRef.current,
        ...options,
      }) || {};
 
    return () => destroy?.();
  }, [id, JSON.stringify(options)]);
 
  return <div {...rest} ref={rootRef} />;
}

Copy"use client";
 
import LayoutLoader from "@/ui/layout/layout-loader";
import { AnimatedEmptyState } from "@/ui/shared/animated-empty-state";
import { DubEmbed } from "@dub/embed-react";
import { CursorRays, Hyperlink, InvoiceDollar, UserCheck } from "@dub/ui/icons";
import { fetcher } from "@dub/utils";
import { useSession } from "next-auth/react";
import useSWRImmutable from "swr/immutable";
 
export function ReferralsPageClient() {
  const { data: session, status } = useSession();
 
  const { data: { publicToken } = {}, isLoading } = useSWRImmutable<{
    publicToken: string;
  }>(session && "/api/user/referrals-token", fetcher, {
    keepPreviousData: true,
  });
 
  if (status === "loading" || isLoading) {
    return <LayoutLoader />;
  }
 
  if (!publicToken) {
    return (
      <div className="p-10">
        <AnimatedEmptyState
          title="Refer a friend"
          description="Activate your referral link to share the word about Dub and earn cash rewards"
          className="border-none"
          cardContent={
            <>
              <Hyperlink className="size-4 text-neutral-700" />
              <div className="h-2.5 w-24 min-w-0 rounded-sm bg-neutral-200" />
              <div className="xs:flex hidden grow items-center justify-end gap-1.5 text-neutral-500">
                <CursorRays className="size-3.5" />
                <UserCheck className="size-3.5" />
                <InvoiceDollar className="size-3.5" />
              </div>
            </>
          }
          pillContent="Coming soon"
        />
      </div>
    );
  }
 
  return <DubEmbed data="referrals" token={publicToken} />;
}

Copyexport const getReferralsEmbedData = async (token: string) => {
  const { programId, partnerId } = (await referralsEmbedToken.get(token)) ?? {};
 
  if (!programId || !partnerId) {
    notFound();
  }

Copyconst programEnrollment = await getProgramEnrollmentOrThrow({
  partnerId,
  programId,
  include: {
    partner: {
      select: {
        id: true,
        name: true,
        email: true,
        username: true,
        country: true,
        tremendousEmail: true,
        defaultPayoutMethod: true,
        platforms: {
          select: {
            type: true,
            identifier: true,
            verifiedAt: true,
          },
        },
      },
    },
    program: {
      select: {
        id: true,
        name: true,
        slug: true,
        domain: true,
        defaultGroupId: true,
        minPayoutAmount: true,
        termsUrl: true,
        embedData: true,
        resources: true,
      },
    },
    links: {
      include: {
        linkReward: {
          include: {
            clickReward: true,
            leadReward: true,
            saleReward: true,
            discount: true,
          },
        },
      },
    },
    partnerGroup: true,
    clickReward: true,
    leadReward: true,
    saleReward: true,
    referralReward: true,
    customReward: true,
    discount: true,
    programPartnerTags: {
      select: {
        partnerTagId: true,
      },
    },
  },
});
 
if (!programEnrollment || !programEnrollment.partnerGroup) {
  notFound();
}

Copyconst { totalClicks, totalLeads, totalConversions } =
  aggregatePartnerLinksStats(links);
 
const [commissions, bounties] = await Promise.all([
  prisma.commission.groupBy({
    by: ["status"],
    _sum: {
      earnings: true,
    },
    _count: {
      id: true,
    },
    where: {
      earnings: {
        gt: 0,
      },
      programId,
      partnerId,
    },
  }),
 
  getBountiesForPartner(programEnrollment),
]);

Copyearnings: {
  upcoming: commissions.reduce((acc, c) => {
    if (c.status === "pending" || c.status === "processed") {
      return acc + (c._sum.earnings ?? 0);
    }
    return acc;
  }, 0),
  paid: commissions.find((c) => c.status === "paid")?._sum.earnings ?? 0,
  totalCount: commissions.reduce((acc, c) => acc + c._count.id, 0),
},

Copyexport default async function ReferralsEmbedPage(props: {
  searchParams: Promise<{
    token: string;
    themeOptions?: string;
    dynamicHeight?: string;
  }>;
}) {
  const searchParams = await props.searchParams;
  const {
    token,
    themeOptions: themeOptionsRaw,
    dynamicHeight: dynamicHeightRaw,
  } = searchParams;
 
  const themeOptions = parseThemeOptions(themeOptionsRaw);
  const dynamicHeight = !!dynamicHeightRaw && dynamicHeightRaw !== "false";
 
  return (
    <>
      <Suspense fallback={<EmbedInlineLoading themeOptions={themeOptions} />}>
        <ReferralsEmbedRSC
          token={token}
          themeOptions={themeOptions}
          dynamicHeight={dynamicHeight}
        />
      </Suspense>
      {dynamicHeight && <DynamicHeightMessenger />}
    </>
  );
}

Copyasync function ReferralsEmbedRSC({
  token,
  themeOptions,
  dynamicHeight,
}: {
  token: string;
  themeOptions: ThemeOptions;
  dynamicHeight: boolean;
}) {
  const embedData = await getReferralsEmbedData(token);
 
  return (
    <ReferralsEmbedPageClient
      {...embedData}
      themeOptions={themeOptions}
      dynamicHeight={dynamicHeight}
    />
  );
}

Copy// POST /api/embed/referrals/links – create links for a partner
export const POST = withReferralsEmbedToken(
  async ({ req, programEnrollment, program, links, group }) => {
    if (!ACTIVE_ENROLLMENT_STATUSES.includes(programEnrollment.status)) {
      throw new DubApiError({
        code: "forbidden",
        message:
          "You cannot create links in this program because your enrollment is not active.",
      });
    }
 
    const { url, key } = createPartnerLinkSchema
      .pick({ url: true, key: true })
      .parse(await parseRequestBody(req));
 
    if (!program.domain || !program.url) {
      throw new DubApiError({
        code: "bad_request",
        message:
          "This program needs a domain and URL set before creating a link.",
      });
    }
 
    if (links.length >= group.maxPartnerLinks) {
      throw new DubApiError({
        code: "bad_request",
        message: `You have reached the limit of ${group.maxPartnerLinks} program links.`,
      });
    }
 
    validatePartnerLinkUrl({ group, url });
 

Copyconst [workspaceOwner, partnerGroup, partner] = await Promise.all([
  prisma.projectUsers.findFirst({
    where: {
      projectId: program.workspaceId,
      role: "owner",
    },
    orderBy: {
      createdAt: "desc",
    },
    include: {
      project: {
        select: {
          id: true,
          webhookEnabled: true,
        },
      },
    },
  }),
 
  prisma.partnerGroup.findUnique({
    where: {
      id: group.id,
    },
    include: {
      partnerGroupDefaultLinks: true,
      utmTemplate: true,
    },
  }),
 
  prisma.partner.findUnique({
    where: {
      id: programEnrollment.partnerId,
    },
    select: {
      name: true,
    },
  }),
]);
 
// shouldn't happen but just in case
if (!partnerGroup) {
  throw new DubApiError({
    code: "not_found",
    message: "This partner is not part of a partner group.",
  });
}
 
const linkUrl = url || partnerGroup.partnerGroupDefaultLinks[0].url;
 
const { link, error, code } = await processLink({
  payload: {
    key: key || undefined,
    url: linkUrl,
    domain: program.domain,
    programId: program.id,
    folderId: program.defaultFolderId,
    tenantId: programEnrollment.tenantId,
    partnerId: programEnrollment.partnerId,
    trackConversion: true,
  },
  workspace: {
    id: program.workspaceId,
    plan: "business",
    users: [{ role: "owner" }],
  },
  userId: workspaceOwner?.userId,
  skipFolderChecks: true, // can't be changed by the partner
  skipProgramChecks: true, // can't be changed by the partner
  skipExternalIdChecks: true, // can't be changed by the partner
});

Copyexport function ReferralsEmbedLeaderboard() {
  const token = useEmbedToken();
 
  const { data: partners, isLoading } = useSWR<
    z.infer<typeof LeaderboardPartnerSchema>[]
  >(
    "/api/embed/referrals/leaderboard",
    (url) =>
      fetcher(url, {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      }),
    {
      keepPreviousData: true,
    },
  );

Copyconst { table, ...tableProps } = useTable({
  data: partners || [],
  loading: isLoading,
  columns: [
    {
      id: "rank",
      header: "Rank",
      size: 40,
      minSize: 40,
      cell: ({ row }) => {
        return (
          <div className="flex w-8 items-center justify-start gap-1 tabular-nums">
            {row.index + 1}
            {row.index <= 2 && (
              <Crown
                className={cn("size-4", {
                  "text-amber-400": row.index === 0,
                  "text-neutral-400": row.index === 1,
                  "text-yellow-900": row.index === 2,
                })}
              />
            )}
          </div>
        );
      },
    },
    {
      id: "name",
      header: "Partner",
      cell: ({ row }) => {
        return (
          <div className="flex items-center gap-2">
            <PartnerAvatar partner={row.original} className="size-5" />
            <Tooltip content="For privacy reasons, the name of the partner is anonymized.">
              <span className="cursor-help text-sm font-medium decoration-dotted underline-offset-2 hover:underline">
                {generateRandomName(row.original.id)}
              </span>
            </Tooltip>
          </div>
        );
      },
    },
    {
      id: "totalCommissions",
      header: "Earnings",
      cell: ({ row }) => {
        return currencyFormatter(row.original.totalCommissions);
      },
    },
  ],
  emptyState: (
    <AnimatedEmptyState
      title="No partners found"
      description="No partners have been added to this program yet."
      cardContent={() => (
        <>
          <Users className="text-content-default size-4" />
          <div className="bg-bg-emphasis h-2.5 w-24 min-w-0 rounded-sm" />
        </>
      )}
      className="border-none md:min-h-fit"
    />
  ),
  thClassName: "border-l-0",
  tdClassName: "border-l-0",
  resourceName: (plural) => `partner${plural ? "s" : ""}`,
});

Copyconst querySchema = partnerProfileAnalyticsQuerySchema.pick({
  event: true,
  start: true,
  end: true,
  groupBy: true,
  saleType: true,
  interval: true,
});
 
// GET /api/embed/referrals/analytics – get analytics for a partner
export const GET = withReferralsEmbedToken(
  async ({ links, program, searchParams }) => {
    if (links.length === 0) {
      return NextResponse.json([]);
    }
 
    const parsedQuery = querySchema.parse(searchParams);
 
    const analytics = await getAnalytics({
      ...parsedQuery,
      workspaceId: program.workspaceId,
      linkId: parseFilterValue(links.map((link) => link.id)),
      dataAvailableFrom: program.startedAt ?? program.createdAt,
    });
 
    return NextResponse.json(analytics);
  },

Copyexport function ReferralsEmbedActivity() {
  const {
    group: { brandColor: color },
    stats: { clicks, leads, conversions },
  } = useReferralsEmbedData();
 
  const token = useEmbedToken();
 
  const isEmpty = clicks === 0 && leads === 0 && conversions === 0;
 
  const analyticsSearchParams = new URLSearchParams({
    event: "composite",
    groupBy: "timeseries",
    interval: "1y",
    saleType: "new",
  });
 
  const { data: analytics } = useSWR<AnalyticsTimeseries[]>(
    !isEmpty &&
      `/api/embed/referrals/analytics?${analyticsSearchParams.toString()}`,
    (url) =>
      fetcher(url, {
        headers: {
          Authorization: `Bearer ${token}`,
        },
      }),
    {
      keepPreviousData: true,
      dedupingInterval: 60000,
    },
  );

Copyconst querySchema = getPartnerEarningsQuerySchema
  .pick({
    start: true,
    end: true,
    page: true,
    pageSize: true,
    interval: true,
    timezone: true,
  })
  .extend({
    withTotal: z
      .string()
      .optional()
      .transform((v) => v?.toLowerCase() === "true")
      .default(false),
  });
 
// GET /api/embed/referrals/earnings – get commissions for a partner from an embed token
export const GET = withReferralsEmbedToken(
  async ({ programEnrollment, searchParams }) => {
    const { withTotal, start, end, pageSize, page, interval, timezone } =
      querySchema.parse(searchParams);
 
    const [earnings, total] = await Promise.all([
      getEarningsForPartner({
        page,