@btst/plugin-affiliate 0.0.0-stage → 1.0.0

package/dist/api/operations.mjs

@@ -0,0 +1,326 @@
+import { defineOperation, definePassthroughOperation, OperationHttpError } from '@btst/stack/plugins/api';
+import { z } from 'zod';
+import { attributionFromRequest, isClickWithinWindow, safeLandingPath, selectAttributionClick, AFFILIATE_COOKIE_NAME } from '../attribution.mjs';
+import { affiliatePermissions } from '../permissions.mjs';
+import { listSchema, idSchema, updatePayoutSchema, createPayoutSchema, updateCommissionSchema, createConversionSchema, trackClickSchema, updatePortalSchema, applicationSchema, updateAffiliateSchema, createAffiliateSchema, affiliateListSchema } from '../schemas.mjs';
+import { exportPayouts, getPayout, listPayouts, getCommission, listCommissions, getReferralClick, getAffiliate, getAffiliateByUserId, getPortal, getAffiliateStats, listAffiliates } from './getters.mjs';
+import { updatePayout, createPayout, updateCommission, createConversion, trackClick, updateAffiliate, createAffiliate, deleteAffiliate } from './mutations.mjs';
+
+function fail(status, message) {
+  throw new OperationHttpError(status, message, "AFFILIATE_ERROR");
+}
+async function requireAffiliate(adapter, id) {
+  return await getAffiliate(adapter, id) ?? fail(404, "Affiliate not found");
+}
+async function affiliateFacts(adapter, id) {
+  const affiliate = await requireAffiliate(adapter, id);
+  return {
+    affiliateId: affiliate.id,
+    userId: affiliate.userId,
+    status: affiliate.status
+  };
+}
+function requireIdentity(identity) {
+  return identity?.id ?? fail(401, "Sign in to manage your affiliate profile");
+}
+function attributionCookie(request) {
+  const value = request?.headers.get("cookie")?.split(";").map((entry) => entry.trim()).find((entry) => entry.startsWith(`${AFFILIATE_COOKIE_NAME}=`))?.slice(AFFILIATE_COOKIE_NAME.length + 1);
+  return value && /^[a-zA-Z0-9_-]{1,200}$/.test(value) ? value : void 0;
+}
+function createAffiliateOperations(adapter, options) {
+  return {
+    listAffiliates: defineOperation({
+      input: affiliateListSchema,
+      permission: affiliatePermissions.affiliate.read,
+      facts: () => ({ scope: "collection" }),
+      execute: async ({ input }) => {
+        const result = await listAffiliates(adapter, input);
+        return {
+          ...result,
+          items: result.items.map((affiliate) => ({ ...affiliate }))
+        };
+      }
+    }),
+    getAffiliate: defineOperation({
+      input: idSchema,
+      permission: affiliatePermissions.affiliate.read,
+      facts: ({ input }) => ({
+        scope: "record",
+        affiliateId: input.id
+      }),
+      execute: async ({ input }) => ({
+        affiliate: { ...await requireAffiliate(adapter, input.id) },
+        stats: { ...await getAffiliateStats(adapter, input.id) }
+      })
+    }),
+    createAffiliate: defineOperation({
+      input: createAffiliateSchema,
+      permission: affiliatePermissions.affiliate.create,
+      facts: () => void 0,
+      execute: async ({ input }) => ({
+        ...await createAffiliate(adapter, input)
+      })
+    }),
+    updateAffiliate: defineOperation({
+      input: idSchema.extend({ data: updateAffiliateSchema }),
+      permission: affiliatePermissions.affiliate.update,
+      facts: ({ input }) => affiliateFacts(adapter, input.id),
+      before: async (context) => {
+        if (context.input.data.status === "approved")
+          await options.hooks?.onBeforeApproveAffiliate?.(
+            await requireAffiliate(adapter, context.input.id),
+            context
+          );
+      },
+      execute: async ({ input, facts }) => ({
+        ...await updateAffiliate(adapter, input.id, input.data, {
+          id: facts.affiliateId,
+          userId: facts.userId,
+          status: facts.status
+        })
+      })
+    }),
+    deleteAffiliate: defineOperation({
+      input: idSchema,
+      permission: affiliatePermissions.affiliate.delete,
+      facts: ({ input }) => affiliateFacts(adapter, input.id),
+      execute: async ({ input, facts }) => {
+        await deleteAffiliate(adapter, input.id, {
+          id: facts.affiliateId,
+          userId: facts.userId,
+          status: facts.status
+        });
+        return { success: true };
+      }
+    }),
+    apply: defineOperation({
+      input: applicationSchema,
+      permission: affiliatePermissions.application.create,
+      facts: () => void 0,
+      execute: async ({ input, identity }) => ({
+        ...await createAffiliate(adapter, {
+          ...input,
+          userId: requireIdentity(identity)
+        })
+      })
+    }),
+    getPortal: defineOperation({
+      input: z.object({}),
+      permission: affiliatePermissions.portal.read,
+      facts: () => void 0,
+      execute: async ({ identity }) => {
+        const portal = await getPortal(
+          adapter,
+          requireIdentity(identity),
+          options.marketingAssets
+        );
+        return {
+          affiliate: portal.affiliate ? { ...portal.affiliate } : null,
+          stats: { ...portal.stats },
+          commissions: portal.commissions.map((commission) => ({
+            ...commission
+          })),
+          payouts: portal.payouts.map((payout) => ({ ...payout })),
+          assets: portal.assets.map((asset) => ({ ...asset }))
+        };
+      }
+    }),
+    updatePortal: defineOperation({
+      input: updatePortalSchema,
+      permission: affiliatePermissions.portal.update,
+      facts: () => void 0,
+      execute: async ({ input, identity }) => {
+        const affiliate = await getAffiliateByUserId(
+          adapter,
+          requireIdentity(identity)
+        ) ?? fail(404, "Apply to the affiliate program first");
+        const updated = await updateAffiliate(
+          adapter,
+          affiliate.id,
+          input
+        );
+        const { notes: _notes, ...profile } = updated;
+        return profile;
+      }
+    }),
+    trackClick: definePassthroughOperation({
+      input: trackClickSchema,
+      permission: affiliatePermissions.tracking.track,
+      access: "public",
+      facts: () => void 0,
+      execute: async ({ input, request }) => {
+        let landingPath;
+        try {
+          landingPath = safeLandingPath(input.landingPath);
+        } catch {
+          fail(400, "Landing path must be a local absolute path");
+        }
+        const destination = new URL(
+          landingPath,
+          options.siteOrigin ?? request?.url ?? "https://affiliate.invalid"
+        );
+        const click = await trackClick(adapter, {
+          ...input,
+          landingPath,
+          referrer: request?.headers.get("referer")?.slice(0, 2048) ?? input.referrer,
+          userAgent: request?.headers.get("user-agent")?.slice(0, 2048) ?? input.userAgent
+        });
+        const previousId = attributionCookie(request);
+        const previous = previousId ? await getReferralClick(adapter, previousId) : null;
+        const previousAffiliate = previous ? await getAffiliate(adapter, previous.affiliateId) : null;
+        const selected = selectAttributionClick(
+          previousAffiliate?.status === "approved" ? previous : null,
+          click,
+          options
+        );
+        const headers = new Headers({
+          Location: options.siteOrigin ? destination.href : destination.pathname + destination.search + destination.hash,
+          "Cache-Control": "no-store, private",
+          "Referrer-Policy": "no-referrer"
+        });
+        if (selected) {
+          const maxAge = Math.max(
+            0,
+            Math.floor(
+              (new Date(selected.createdAt).getTime() + (options.attributionWindowDays ?? 30) * 864e5 - Date.now()) / 1e3
+            )
+          );
+          headers.set(
+            "Set-Cookie",
+            `${AFFILIATE_COOKIE_NAME}=${selected.id}; Path=/; Max-Age=${maxAge}; HttpOnly; SameSite=Lax${request && new URL(request.url).protocol === "https:" ? "; Secure" : ""}`
+          );
+        }
+        return new Response(null, { status: 302, headers });
+      }
+    }),
+    createConversion: defineOperation({
+      input: createConversionSchema,
+      permission: affiliatePermissions.conversion.create,
+      facts: () => void 0,
+      execute: async ({ input, request }) => {
+        let requestAttribution = request ? attributionFromRequest(request) : void 0;
+        if (!input.attribution) {
+          const cookieId = attributionCookie(request);
+          const click = cookieId ? await getReferralClick(adapter, cookieId) : null;
+          if (click && isClickWithinWindow(click, options.attributionWindowDays) && (await getAffiliate(adapter, click.affiliateId))?.status === "approved")
+            requestAttribution = { clickId: click.id };
+        }
+        if (!input.attribution && !createConversionSchema.shape.attribution.safeParse(
+          requestAttribution
+        ).success)
+          fail(400, "Invalid referral attribution");
+        const result = await createConversion(
+          adapter,
+          {
+            ...input,
+            attribution: input.attribution ?? requestAttribution
+          },
+          options
+        );
+        return result ? {
+          conversion: { ...result.conversion },
+          commission: { ...result.commission }
+        } : null;
+      },
+      after: async (context) => {
+        if (context.result)
+          await options.hooks?.onAfterConversion?.(
+            context.result.conversion,
+            context.result.commission,
+            context
+          );
+      }
+    }),
+    listCommissions: defineOperation({
+      input: listSchema,
+      permission: affiliatePermissions.commission.read,
+      facts: () => void 0,
+      execute: async ({ input }) => {
+        const result = await listCommissions(adapter, input);
+        return {
+          ...result,
+          items: result.items.map((commission) => ({ ...commission }))
+        };
+      }
+    }),
+    updateCommission: defineOperation({
+      input: idSchema.extend({ data: updateCommissionSchema }),
+      permission: affiliatePermissions.commission.update,
+      facts: async ({ input }) => {
+        const commission = await getCommission(adapter, input.id) ?? fail(404, "Commission not found");
+        return {
+          commissionId: commission.id,
+          affiliateId: commission.affiliateId,
+          status: commission.status
+        };
+      },
+      execute: async ({ input, facts }) => ({
+        ...await updateCommission(adapter, input.id, input.data, {
+          id: facts.commissionId,
+          affiliateId: facts.affiliateId,
+          status: facts.status
+        })
+      })
+    }),
+    listPayouts: defineOperation({
+      input: listSchema,
+      permission: affiliatePermissions.payout.read,
+      facts: () => void 0,
+      execute: async ({ input }) => {
+        const result = await listPayouts(adapter, input);
+        return {
+          ...result,
+          items: result.items.map((payout) => ({ ...payout }))
+        };
+      }
+    }),
+    createPayout: defineOperation({
+      input: createPayoutSchema,
+      permission: affiliatePermissions.payout.create,
+      facts: async ({ input }) => {
+        await requireAffiliate(adapter, input.affiliateId);
+        return { affiliateId: input.affiliateId, currency: input.currency };
+      },
+      before: (context) => options.hooks?.onBeforePayout?.(context.input, context),
+      execute: async ({ input }) => ({
+        ...await createPayout(adapter, {
+          ...input,
+          commissionIds: input.commissionIds ? [...input.commissionIds] : void 0
+        })
+      })
+    }),
+    updatePayout: defineOperation({
+      input: idSchema.extend({ data: updatePayoutSchema }),
+      permission: affiliatePermissions.payout.update,
+      facts: async ({ input }) => {
+        const payout = await getPayout(adapter, input.id) ?? fail(404, "Payout not found");
+        return {
+          payoutId: payout.id,
+          affiliateId: payout.affiliateId,
+          status: payout.status
+        };
+      },
+      execute: async ({ input, facts }) => ({
+        ...await updatePayout(adapter, input.id, input.data, {
+          id: facts.payoutId,
+          affiliateId: facts.affiliateId,
+          status: facts.status
+        })
+      }),
+      after: async (context) => {
+        if (context.result.status === "sent")
+          await options.hooks?.onAfterPayout?.(context.result, context);
+      }
+    }),
+    exportPayouts: defineOperation({
+      input: listSchema,
+      permission: affiliatePermissions.payout.export,
+      facts: () => void 0,
+      execute: async ({ input }) => ({
+        csv: await exportPayouts(adapter, input)
+      })
+    })
+  };
+}
+
+export { createAffiliateOperations };

package/dist/api/plugin.cjs

@@ -0,0 +1,146 @@
+'use strict';
+
+const api = require('@btst/stack/plugins/api');
+const zod = require('zod');
+const commission = require('../commission.cjs');
+const db = require('../db.cjs');
+const schemas = require('../schemas.cjs');
+const operations = require('./operations.cjs');
+
+const affiliateBackendPlugin = (options = {}) => {
+  const assetURL = zod.z.url({ protocol: /^https?$/ });
+  zod.z.object({
+    siteOrigin: assetURL.refine((value) => {
+      const url = new URL(value);
+      return !url.username && !url.password && url.pathname === "/" && !url.search && !url.hash;
+    }, "siteOrigin must contain only an HTTP(S) origin").optional(),
+    attributionWindowDays: zod.z.number().int().min(1).max(3650).optional(),
+    attributionMode: zod.z.enum(["first_touch", "last_touch"]).optional(),
+    defaultCommissionType: zod.z.enum(["percent", "flat"]).optional(),
+    defaultCommissionValue: zod.z.number().finite().nonnegative().optional(),
+    marketingAssets: zod.z.array(
+      zod.z.object({
+        name: zod.z.string().min(1),
+        url: assetURL,
+        description: zod.z.string().optional(),
+        bannerUrl: assetURL.optional()
+      })
+    ).optional()
+  }).parse(options);
+  commission.calculateCommission(
+    0,
+    options.defaultCommissionType ?? "percent",
+    options.defaultCommissionValue ?? 20
+  );
+  return api.defineBackendPlugin({
+    id: "affiliate",
+    dbPlugin: db.affiliateSchema,
+    operations: (adapter, context) => {
+      if (!context?.auth)
+        throw new Error(
+          "Affiliate requires a server auth adapter configured with affiliatePermissions"
+        );
+      return operations.createAffiliateOperations(adapter, options);
+    },
+    routes: (_adapter, _context, operations) => ({
+      listAffiliates: api.createEndpoint(
+        "/affiliate/affiliates",
+        { method: "GET", query: schemas.affiliateListSchema, requireRequest: true },
+        operations.listAffiliates.route((ctx) => ctx.query)
+      ),
+      getAffiliate: api.createEndpoint(
+        "/affiliate/affiliates/:id",
+        { method: "GET", requireRequest: true },
+        operations.getAffiliate.route((ctx) => ({ id: ctx.params.id }))
+      ),
+      createAffiliate: api.createEndpoint(
+        "/affiliate/affiliates",
+        { method: "POST", body: schemas.createAffiliateSchema, requireRequest: true },
+        operations.createAffiliate.route((ctx) => ctx.body)
+      ),
+      updateAffiliate: api.createEndpoint(
+        "/affiliate/affiliates/:id",
+        { method: "PUT", body: schemas.updateAffiliateSchema, requireRequest: true },
+        operations.updateAffiliate.route((ctx) => ({
+          id: ctx.params.id,
+          data: ctx.body
+        }))
+      ),
+      deleteAffiliate: api.createEndpoint(
+        "/affiliate/affiliates/:id",
+        { method: "DELETE", requireRequest: true },
+        operations.deleteAffiliate.route((ctx) => ({ id: ctx.params.id }))
+      ),
+      apply: api.createEndpoint(
+        "/affiliate/apply",
+        { method: "POST", body: schemas.applicationSchema, requireRequest: true },
+        operations.apply.route((ctx) => ctx.body)
+      ),
+      getPortal: api.createEndpoint(
+        "/affiliate/portal",
+        { method: "GET", requireRequest: true },
+        operations.getPortal.route(() => ({}))
+      ),
+      updatePortal: api.createEndpoint(
+        "/affiliate/portal",
+        { method: "PUT", body: schemas.updatePortalSchema, requireRequest: true },
+        operations.updatePortal.route((ctx) => ctx.body)
+      ),
+      trackClick: api.createEndpoint(
+        "/affiliate/track/:code",
+        {
+          method: "GET",
+          query: zod.z.object({ to: zod.z.string().max(2048).optional() }),
+          requireRequest: true
+        },
+        operations.trackClick.route((ctx) => ({
+          code: ctx.params.code,
+          landingPath: ctx.query.to
+        }))
+      ),
+      createConversion: api.createEndpoint(
+        "/affiliate/conversions",
+        { method: "POST", body: schemas.createConversionSchema, requireRequest: true },
+        operations.createConversion.route((ctx) => ctx.body)
+      ),
+      listCommissions: api.createEndpoint(
+        "/affiliate/commissions",
+        { method: "GET", query: schemas.listSchema, requireRequest: true },
+        operations.listCommissions.route((ctx) => ctx.query)
+      ),
+      updateCommission: api.createEndpoint(
+        "/affiliate/commissions/:id",
+        { method: "PUT", body: schemas.updateCommissionSchema, requireRequest: true },
+        operations.updateCommission.route((ctx) => ({
+          id: ctx.params.id,
+          data: ctx.body
+        }))
+      ),
+      listPayouts: api.createEndpoint(
+        "/affiliate/payouts",
+        { method: "GET", query: schemas.listSchema, requireRequest: true },
+        operations.listPayouts.route((ctx) => ctx.query)
+      ),
+      createPayout: api.createEndpoint(
+        "/affiliate/payouts",
+        { method: "POST", body: schemas.createPayoutSchema, requireRequest: true },
+        operations.createPayout.route((ctx) => ctx.body)
+      ),
+      updatePayout: api.createEndpoint(
+        "/affiliate/payouts/:id",
+        { method: "PUT", body: schemas.updatePayoutSchema, requireRequest: true },
+        operations.updatePayout.route((ctx) => ({
+          id: ctx.params.id,
+          data: ctx.body
+        }))
+      ),
+      exportPayouts: api.createEndpoint(
+        "/affiliate/payouts/export",
+        { method: "GET", query: schemas.listSchema, requireRequest: true },
+        operations.exportPayouts.route((ctx) => ctx.query)
+      )
+    })
+  });
+};
+
+exports.affiliateBackendPlugin = affiliateBackendPlugin;

package/dist/api/plugin.mjs

@@ -0,0 +1,144 @@
+import { defineBackendPlugin, createEndpoint } from '@btst/stack/plugins/api';
+import { z } from 'zod';
+import { calculateCommission } from '../commission.mjs';
+import { affiliateSchema } from '../db.mjs';
+import { listSchema, updatePayoutSchema, createPayoutSchema, updateCommissionSchema, createConversionSchema, updatePortalSchema, applicationSchema, updateAffiliateSchema, createAffiliateSchema, affiliateListSchema } from '../schemas.mjs';
+import { createAffiliateOperations } from './operations.mjs';
+
+const affiliateBackendPlugin = (options = {}) => {
+  const assetURL = z.url({ protocol: /^https?$/ });
+  z.object({
+    siteOrigin: assetURL.refine((value) => {
+      const url = new URL(value);
+      return !url.username && !url.password && url.pathname === "/" && !url.search && !url.hash;
+    }, "siteOrigin must contain only an HTTP(S) origin").optional(),
+    attributionWindowDays: z.number().int().min(1).max(3650).optional(),
+    attributionMode: z.enum(["first_touch", "last_touch"]).optional(),
+    defaultCommissionType: z.enum(["percent", "flat"]).optional(),
+    defaultCommissionValue: z.number().finite().nonnegative().optional(),
+    marketingAssets: z.array(
+      z.object({
+        name: z.string().min(1),
+        url: assetURL,
+        description: z.string().optional(),
+        bannerUrl: assetURL.optional()
+      })
+    ).optional()
+  }).parse(options);
+  calculateCommission(
+    0,
+    options.defaultCommissionType ?? "percent",
+    options.defaultCommissionValue ?? 20
+  );
+  return defineBackendPlugin({
+    id: "affiliate",
+    dbPlugin: affiliateSchema,
+    operations: (adapter, context) => {
+      if (!context?.auth)
+        throw new Error(
+          "Affiliate requires a server auth adapter configured with affiliatePermissions"
+        );
+      return createAffiliateOperations(adapter, options);
+    },
+    routes: (_adapter, _context, operations) => ({
+      listAffiliates: createEndpoint(
+        "/affiliate/affiliates",
+        { method: "GET", query: affiliateListSchema, requireRequest: true },
+        operations.listAffiliates.route((ctx) => ctx.query)
+      ),
+      getAffiliate: createEndpoint(
+        "/affiliate/affiliates/:id",
+        { method: "GET", requireRequest: true },
+        operations.getAffiliate.route((ctx) => ({ id: ctx.params.id }))
+      ),
+      createAffiliate: createEndpoint(
+        "/affiliate/affiliates",
+        { method: "POST", body: createAffiliateSchema, requireRequest: true },
+        operations.createAffiliate.route((ctx) => ctx.body)
+      ),
+      updateAffiliate: createEndpoint(
+        "/affiliate/affiliates/:id",
+        { method: "PUT", body: updateAffiliateSchema, requireRequest: true },
+        operations.updateAffiliate.route((ctx) => ({
+          id: ctx.params.id,
+          data: ctx.body
+        }))
+      ),
+      deleteAffiliate: createEndpoint(
+        "/affiliate/affiliates/:id",
+        { method: "DELETE", requireRequest: true },
+        operations.deleteAffiliate.route((ctx) => ({ id: ctx.params.id }))
+      ),
+      apply: createEndpoint(
+        "/affiliate/apply",
+        { method: "POST", body: applicationSchema, requireRequest: true },
+        operations.apply.route((ctx) => ctx.body)
+      ),
+      getPortal: createEndpoint(
+        "/affiliate/portal",
+        { method: "GET", requireRequest: true },
+        operations.getPortal.route(() => ({}))
+      ),
+      updatePortal: createEndpoint(
+        "/affiliate/portal",
+        { method: "PUT", body: updatePortalSchema, requireRequest: true },
+        operations.updatePortal.route((ctx) => ctx.body)
+      ),
+      trackClick: createEndpoint(
+        "/affiliate/track/:code",
+        {
+          method: "GET",
+          query: z.object({ to: z.string().max(2048).optional() }),
+          requireRequest: true
+        },
+        operations.trackClick.route((ctx) => ({
+          code: ctx.params.code,
+          landingPath: ctx.query.to
+        }))
+      ),
+      createConversion: createEndpoint(
+        "/affiliate/conversions",
+        { method: "POST", body: createConversionSchema, requireRequest: true },
+        operations.createConversion.route((ctx) => ctx.body)
+      ),
+      listCommissions: createEndpoint(
+        "/affiliate/commissions",
+        { method: "GET", query: listSchema, requireRequest: true },
+        operations.listCommissions.route((ctx) => ctx.query)
+      ),
+      updateCommission: createEndpoint(
+        "/affiliate/commissions/:id",
+        { method: "PUT", body: updateCommissionSchema, requireRequest: true },
+        operations.updateCommission.route((ctx) => ({
+          id: ctx.params.id,
+          data: ctx.body
+        }))
+      ),
+      listPayouts: createEndpoint(
+        "/affiliate/payouts",
+        { method: "GET", query: listSchema, requireRequest: true },
+        operations.listPayouts.route((ctx) => ctx.query)
+      ),
+      createPayout: createEndpoint(
+        "/affiliate/payouts",
+        { method: "POST", body: createPayoutSchema, requireRequest: true },
+        operations.createPayout.route((ctx) => ctx.body)
+      ),
+      updatePayout: createEndpoint(
+        "/affiliate/payouts/:id",
+        { method: "PUT", body: updatePayoutSchema, requireRequest: true },
+        operations.updatePayout.route((ctx) => ({
+          id: ctx.params.id,
+          data: ctx.body
+        }))
+      ),
+      exportPayouts: createEndpoint(
+        "/affiliate/payouts/export",
+        { method: "GET", query: listSchema, requireRequest: true },
+        operations.exportPayouts.route((ctx) => ctx.query)
+      )
+    })
+  });
+};
+
+export { affiliateBackendPlugin };