@btst/plugin-affiliate 0.0.0-stage → 1.0.0

package/LICENSE.md

@@ -0,0 +1,17 @@
+The MIT License (MIT)
+Copyright (c) 2025 - present, olliethedev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without restriction,
+including without limitation the rights to use, copy, modify, merge, publish, distribute,
+sublicense, and/or sell copies of the Software, and to permit persons to whom the Software
+is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/dist/api/getters.cjs

@@ -0,0 +1,182 @@
+'use strict';
+
+const api = require('@btst/stack/plugins/api');
+
+function serializeAffiliateRecord(record) {
+  const { lockVersion: _lockVersion, ...result } = record;
+  for (const field of ["createdAt", "updatedAt", "paidAt"]) {
+    const value = result[field];
+    if (value instanceof Date) result[field] = value.toISOString();
+  }
+  return result;
+}
+async function byField(adapter, model, field, value) {
+  const row = await adapter.findOne({
+    model,
+    where: [{ field, value, operator: "eq" }]
+  });
+  return row ? serializeAffiliateRecord(row) : null;
+}
+const getAffiliate = (adapter, id) => byField(adapter, "affiliate", "id", id);
+const getAffiliateByUserId = (adapter, userId) => byField(adapter, "affiliate", "userId", userId);
+const getAffiliateByCode = (adapter, code) => byField(adapter, "affiliate", "code", code);
+const getReferralClick = (adapter, id) => byField(adapter, "referralClick", "id", id);
+const getCommission = (adapter, id) => byField(adapter, "affiliateCommission", "id", id);
+const getPayout = (adapter, id) => byField(adapter, "affiliatePayout", "id", id);
+const getConversionByExternalRef = (adapter, externalRef) => byField(
+  adapter,
+  "affiliateConversion",
+  "externalRef",
+  externalRef
+);
+async function list(adapter, model, params = {}) {
+  const where = [];
+  for (const field of ["affiliateId", "status", "currency"]) {
+    const value = params[field];
+    if (value) where.push({ field, value, operator: "eq" });
+  }
+  const limit = params.limit ?? 50;
+  const offset = params.offset ?? 0;
+  const [rows, total] = await Promise.all([
+    adapter.findMany({
+      model,
+      where,
+      limit,
+      offset,
+      sortBy: { field: "createdAt", direction: "desc" }
+    }),
+    adapter.count({ model, where })
+  ]);
+  return {
+    items: rows.map((row) => serializeAffiliateRecord(row)),
+    total,
+    limit,
+    offset
+  };
+}
+const listAffiliates = (adapter, params) => list(adapter, "affiliate", {
+  limit: params?.limit,
+  offset: params?.offset,
+  status: params?.status
+});
+const listCommissions = (adapter, params) => list(adapter, "affiliateCommission", params);
+const listPayouts = (adapter, params) => list(adapter, "affiliatePayout", params);
+async function allRows(adapter, model, where = []) {
+  const items = [];
+  for (let offset = 0; ; offset += 100) {
+    const rows = await adapter.findMany({
+      model,
+      where,
+      limit: 100,
+      offset,
+      sortBy: { field: "id", direction: "asc" }
+    });
+    items.push(...rows.map((row) => serializeAffiliateRecord(row)));
+    if (rows.length < 100) return items;
+  }
+}
+async function getAffiliateStats(adapter, affiliateId) {
+  const where = [
+    { field: "affiliateId", value: affiliateId, operator: "eq" }
+  ];
+  const [clicks, conversions, commissions] = await Promise.all([
+    adapter.count({ model: "referralClick", where }),
+    adapter.count({ model: "affiliateConversion", where }),
+    allRows(adapter, "affiliateCommission", where)
+  ]);
+  const currencies = /* @__PURE__ */ new Map();
+  for (const commission of commissions) {
+    const total = currencies.get(commission.currency) ?? {
+      currency: commission.currency,
+      pending: 0,
+      approved: 0,
+      paid: 0,
+      voided: 0
+    };
+    const next = BigInt(total[commission.status]) + BigInt(commission.amount);
+    if (next > BigInt(Number.MAX_SAFE_INTEGER))
+      throw new api.OperationHttpError(
+        409,
+        "Commission total exceeds safe integer range",
+        "AFFILIATE_AMOUNT_OVERFLOW"
+      );
+    total[commission.status] = Number(next);
+    currencies.set(commission.currency, total);
+  }
+  return {
+    clicks,
+    conversions,
+    totals: [...currencies.values()].sort(
+      (a, b) => a.currency.localeCompare(b.currency)
+    )
+  };
+}
+async function getPortal(adapter, userId, assets = []) {
+  const affiliate = await getAffiliateByUserId(adapter, userId);
+  if (!affiliate)
+    return {
+      affiliate: null,
+      stats: { clicks: 0, conversions: 0, totals: [] },
+      commissions: [],
+      payouts: [],
+      assets
+    };
+  const [stats, commissions, payouts] = await Promise.all([
+    getAffiliateStats(adapter, affiliate.id),
+    listCommissions(adapter, { affiliateId: affiliate.id, limit: 100 }),
+    listPayouts(adapter, { affiliateId: affiliate.id, limit: 100 })
+  ]);
+  const { notes: _notes, ...profile } = affiliate;
+  return {
+    affiliate: profile,
+    stats,
+    commissions: commissions.items,
+    payouts: payouts.items,
+    assets
+  };
+}
+function csvCell(value) {
+  let text = value == null ? "" : String(value);
+  if (/^[\s]*[=+\-@\t\r\n]/.test(text)) text = `'${text}`;
+  return `"${text.replace(/"/g, '""')}"`;
+}
+async function exportPayouts(adapter, params = {}) {
+  const where = [];
+  for (const field of ["affiliateId", "status", "currency"]) {
+    const value = params[field];
+    if (value) where.push({ field, value, operator: "eq" });
+  }
+  const payouts = await allRows(adapter, "affiliatePayout", where);
+  const fields = [
+    "id",
+    "affiliateId",
+    "amount",
+    "currency",
+    "status",
+    "reference",
+    "paidAt",
+    "createdAt"
+  ];
+  return [
+    fields.map(csvCell).join(","),
+    ...payouts.map(
+      (row) => fields.map((field) => csvCell(row[field])).join(",")
+    )
+  ].join("\r\n");
+}
+
+exports.allRows = allRows;
+exports.exportPayouts = exportPayouts;
+exports.getAffiliate = getAffiliate;
+exports.getAffiliateByCode = getAffiliateByCode;
+exports.getAffiliateByUserId = getAffiliateByUserId;
+exports.getAffiliateStats = getAffiliateStats;
+exports.getCommission = getCommission;
+exports.getConversionByExternalRef = getConversionByExternalRef;
+exports.getPayout = getPayout;
+exports.getPortal = getPortal;
+exports.getReferralClick = getReferralClick;
+exports.listAffiliates = listAffiliates;
+exports.listCommissions = listCommissions;
+exports.listPayouts = listPayouts;
+exports.serializeAffiliateRecord = serializeAffiliateRecord;

package/dist/api/getters.mjs

@@ -0,0 +1,166 @@
+import { OperationHttpError } from '@btst/stack/plugins/api';
+
+function serializeAffiliateRecord(record) {
+  const { lockVersion: _lockVersion, ...result } = record;
+  for (const field of ["createdAt", "updatedAt", "paidAt"]) {
+    const value = result[field];
+    if (value instanceof Date) result[field] = value.toISOString();
+  }
+  return result;
+}
+async function byField(adapter, model, field, value) {
+  const row = await adapter.findOne({
+    model,
+    where: [{ field, value, operator: "eq" }]
+  });
+  return row ? serializeAffiliateRecord(row) : null;
+}
+const getAffiliate = (adapter, id) => byField(adapter, "affiliate", "id", id);
+const getAffiliateByUserId = (adapter, userId) => byField(adapter, "affiliate", "userId", userId);
+const getAffiliateByCode = (adapter, code) => byField(adapter, "affiliate", "code", code);
+const getReferralClick = (adapter, id) => byField(adapter, "referralClick", "id", id);
+const getCommission = (adapter, id) => byField(adapter, "affiliateCommission", "id", id);
+const getPayout = (adapter, id) => byField(adapter, "affiliatePayout", "id", id);
+const getConversionByExternalRef = (adapter, externalRef) => byField(
+  adapter,
+  "affiliateConversion",
+  "externalRef",
+  externalRef
+);
+async function list(adapter, model, params = {}) {
+  const where = [];
+  for (const field of ["affiliateId", "status", "currency"]) {
+    const value = params[field];
+    if (value) where.push({ field, value, operator: "eq" });
+  }
+  const limit = params.limit ?? 50;
+  const offset = params.offset ?? 0;
+  const [rows, total] = await Promise.all([
+    adapter.findMany({
+      model,
+      where,
+      limit,
+      offset,
+      sortBy: { field: "createdAt", direction: "desc" }
+    }),
+    adapter.count({ model, where })
+  ]);
+  return {
+    items: rows.map((row) => serializeAffiliateRecord(row)),
+    total,
+    limit,
+    offset
+  };
+}
+const listAffiliates = (adapter, params) => list(adapter, "affiliate", {
+  limit: params?.limit,
+  offset: params?.offset,
+  status: params?.status
+});
+const listCommissions = (adapter, params) => list(adapter, "affiliateCommission", params);
+const listPayouts = (adapter, params) => list(adapter, "affiliatePayout", params);
+async function allRows(adapter, model, where = []) {
+  const items = [];
+  for (let offset = 0; ; offset += 100) {
+    const rows = await adapter.findMany({
+      model,
+      where,
+      limit: 100,
+      offset,
+      sortBy: { field: "id", direction: "asc" }
+    });
+    items.push(...rows.map((row) => serializeAffiliateRecord(row)));
+    if (rows.length < 100) return items;
+  }
+}
+async function getAffiliateStats(adapter, affiliateId) {
+  const where = [
+    { field: "affiliateId", value: affiliateId, operator: "eq" }
+  ];
+  const [clicks, conversions, commissions] = await Promise.all([
+    adapter.count({ model: "referralClick", where }),
+    adapter.count({ model: "affiliateConversion", where }),
+    allRows(adapter, "affiliateCommission", where)
+  ]);
+  const currencies = /* @__PURE__ */ new Map();
+  for (const commission of commissions) {
+    const total = currencies.get(commission.currency) ?? {
+      currency: commission.currency,
+      pending: 0,
+      approved: 0,
+      paid: 0,
+      voided: 0
+    };
+    const next = BigInt(total[commission.status]) + BigInt(commission.amount);
+    if (next > BigInt(Number.MAX_SAFE_INTEGER))
+      throw new OperationHttpError(
+        409,
+        "Commission total exceeds safe integer range",
+        "AFFILIATE_AMOUNT_OVERFLOW"
+      );
+    total[commission.status] = Number(next);
+    currencies.set(commission.currency, total);
+  }
+  return {
+    clicks,
+    conversions,
+    totals: [...currencies.values()].sort(
+      (a, b) => a.currency.localeCompare(b.currency)
+    )
+  };
+}
+async function getPortal(adapter, userId, assets = []) {
+  const affiliate = await getAffiliateByUserId(adapter, userId);
+  if (!affiliate)
+    return {
+      affiliate: null,
+      stats: { clicks: 0, conversions: 0, totals: [] },
+      commissions: [],
+      payouts: [],
+      assets
+    };
+  const [stats, commissions, payouts] = await Promise.all([
+    getAffiliateStats(adapter, affiliate.id),
+    listCommissions(adapter, { affiliateId: affiliate.id, limit: 100 }),
+    listPayouts(adapter, { affiliateId: affiliate.id, limit: 100 })
+  ]);
+  const { notes: _notes, ...profile } = affiliate;
+  return {
+    affiliate: profile,
+    stats,
+    commissions: commissions.items,
+    payouts: payouts.items,
+    assets
+  };
+}
+function csvCell(value) {
+  let text = value == null ? "" : String(value);
+  if (/^[\s]*[=+\-@\t\r\n]/.test(text)) text = `'${text}`;
+  return `"${text.replace(/"/g, '""')}"`;
+}
+async function exportPayouts(adapter, params = {}) {
+  const where = [];
+  for (const field of ["affiliateId", "status", "currency"]) {
+    const value = params[field];
+    if (value) where.push({ field, value, operator: "eq" });
+  }
+  const payouts = await allRows(adapter, "affiliatePayout", where);
+  const fields = [
+    "id",
+    "affiliateId",
+    "amount",
+    "currency",
+    "status",
+    "reference",
+    "paidAt",
+    "createdAt"
+  ];
+  return [
+    fields.map(csvCell).join(","),
+    ...payouts.map(
+      (row) => fields.map((field) => csvCell(row[field])).join(",")
+    )
+  ].join("\r\n");
+}
+
+export { allRows, exportPayouts, getAffiliate, getAffiliateByCode, getAffiliateByUserId, getAffiliateStats, getCommission, getConversionByExternalRef, getPayout, getPortal, getReferralClick, listAffiliates, listCommissions, listPayouts, serializeAffiliateRecord };

package/dist/api/index.cjs

@@ -0,0 +1,49 @@
+'use strict';
+
+const plugin = require('./plugin.cjs');
+const db = require('../db.cjs');
+const permissions = require('../permissions.cjs');
+const getters = require('./getters.cjs');
+const mutations = require('./mutations.cjs');
+const attribution = require('../attribution.cjs');
+const commission = require('../commission.cjs');
+
+
+
+exports.affiliateBackendPlugin = plugin.affiliateBackendPlugin;
+exports.affiliateSchema = db.affiliateSchema;
+exports.affiliatePermissions = permissions.affiliatePermissions;
+exports.allRows = getters.allRows;
+exports.exportPayouts = getters.exportPayouts;
+exports.getAffiliate = getters.getAffiliate;
+exports.getAffiliateByCode = getters.getAffiliateByCode;
+exports.getAffiliateByUserId = getters.getAffiliateByUserId;
+exports.getAffiliateStats = getters.getAffiliateStats;
+exports.getCommission = getters.getCommission;
+exports.getConversionByExternalRef = getters.getConversionByExternalRef;
+exports.getPayout = getters.getPayout;
+exports.getPortal = getters.getPortal;
+exports.getReferralClick = getters.getReferralClick;
+exports.listAffiliates = getters.listAffiliates;
+exports.listCommissions = getters.listCommissions;
+exports.listPayouts = getters.listPayouts;
+exports.serializeAffiliateRecord = getters.serializeAffiliateRecord;
+exports.createAffiliate = mutations.createAffiliate;
+exports.createConversion = mutations.createConversion;
+exports.createPayout = mutations.createPayout;
+exports.deleteAffiliate = mutations.deleteAffiliate;
+exports.trackClick = mutations.trackClick;
+exports.updateAffiliate = mutations.updateAffiliate;
+exports.updateCommission = mutations.updateCommission;
+exports.updatePayout = mutations.updatePayout;
+exports.withAffiliateTransaction = mutations.withAffiliateTransaction;
+exports.AFFILIATE_COOKIE_NAME = attribution.AFFILIATE_COOKIE_NAME;
+exports.attributionFromRequest = attribution.attributionFromRequest;
+exports.createReferralLink = attribution.createReferralLink;
+exports.createTrackingLink = attribution.createTrackingLink;
+exports.getReferralRedirect = attribution.getReferralRedirect;
+exports.isClickWithinWindow = attribution.isClickWithinWindow;
+exports.referralCodeFromURL = attribution.referralCodeFromURL;
+exports.safeLandingPath = attribution.safeLandingPath;
+exports.selectAttributionClick = attribution.selectAttributionClick;
+exports.calculateCommission = commission.calculateCommission;