@btst/plugin-affiliate 0.0.0-stage → 1.0.0-beta.0

package/dist/schemas.mjs

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+
+const affiliateCodeSchema = z.string().trim().min(3).max(64).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+const moneySchema = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+const currencySchema = z.string().regex(/^[A-Z]{3}$/);
+const affiliateStatusSchema = z.enum([
+  "pending",
+  "approved",
+  "suspended"
+]);
+const commissionTypeSchema = z.enum(["percent", "flat"]);
+z.enum([
+  "pending",
+  "approved",
+  "paid",
+  "voided"
+]);
+z.enum(["pending", "sent", "failed"]);
+const idSchema = z.object({ id: z.string().min(1) });
+const listSchema = z.object({
+  limit: z.coerce.number().int().min(1).max(100).optional(),
+  offset: z.coerce.number().int().nonnegative().optional(),
+  affiliateId: z.string().min(1).optional(),
+  status: z.string().optional(),
+  currency: currencySchema.optional()
+});
+const affiliateListSchema = listSchema.pick({ limit: true, offset: true, status: true }).extend({ status: affiliateStatusSchema.optional() });
+const applicationSchema = z.object({
+  name: z.string().trim().min(1).max(200),
+  email: z.email().max(320),
+  code: affiliateCodeSchema.optional(),
+  payoutDetails: z.string().max(1e4).optional()
+});
+const createAffiliateSchema = applicationSchema.extend({
+  userId: z.string().min(1)
+});
+const updateAffiliateSchema = applicationSchema.partial().extend({
+  payoutDetails: z.string().max(1e4).nullable().optional(),
+  status: affiliateStatusSchema.optional(),
+  notes: z.string().max(1e4).nullable().optional(),
+  commissionType: commissionTypeSchema.nullable().optional(),
+  commissionValue: z.number().finite().nonnegative().nullable().optional()
+});
+const updatePortalSchema = applicationSchema.partial().extend({ payoutDetails: z.string().max(1e4).nullable().optional() });
+const trackClickSchema = z.object({
+  code: affiliateCodeSchema,
+  landingPath: z.string().max(2048).optional(),
+  referrer: z.string().max(2048).optional(),
+  ipHash: z.string().max(256).optional(),
+  userAgent: z.string().max(2048).optional()
+});
+const createConversionSchema = z.object({
+  externalRef: z.string().min(1).max(255).optional(),
+  amount: moneySchema,
+  currency: currencySchema.default("USD"),
+  attribution: z.object({
+    code: affiliateCodeSchema.optional(),
+    clickId: z.string().min(1).optional()
+  }).refine(
+    (v) => v.code || v.clickId,
+    "Attribution requires a code or click ID"
+  ).optional()
+});
+const updateCommissionSchema = z.object({
+  status: z.enum(["approved", "voided"])
+});
+const createPayoutSchema = z.object({
+  affiliateId: z.string().min(1),
+  currency: currencySchema,
+  commissionIds: z.array(z.string().min(1)).min(1).max(1e3).optional()
+});
+const updatePayoutSchema = z.object({
+  status: z.enum(["sent", "failed"]),
+  reference: z.string().max(1e3).optional()
+});
+
+export { affiliateCodeSchema, affiliateListSchema, affiliateStatusSchema, applicationSchema, commissionTypeSchema, createAffiliateSchema, createConversionSchema, createPayoutSchema, currencySchema, idSchema, listSchema, moneySchema, trackClickSchema, updateAffiliateSchema, updateCommissionSchema, updatePayoutSchema, updatePortalSchema };

package/dist/style.css

@@ -0,0 +1,313 @@
+
+.affiliate-page {
+	max-width: 1160px;
+	margin: 0 auto;
+	padding: 32px 24px;
+	color: var(--foreground, #0f172a);
+	font: inherit;
+	font-size: 14px;
+	line-height: 1.5;
+}
+.affiliate-page > * + * {
+	margin-top: 24px;
+}
+.affiliate-page h1 {
+	margin: 0;
+	font-size: 30px;
+	font-weight: 600;
+	letter-spacing: -0.025em;
+	overflow-wrap: anywhere;
+}
+.affiliate-page h2 {
+	margin: 0;
+	font-size: 20px;
+	font-weight: 500;
+}
+.affiliate-page p {
+	margin: 0;
+	max-width: 75ch;
+	overflow-wrap: anywhere;
+}
+.affiliate-heading,
+.affiliate-section-heading,
+.affiliate-pagination {
+	display: flex;
+	align-items: center;
+	justify-content: space-between;
+	flex-wrap: wrap;
+	gap: 16px;
+}
+.affiliate-heading > div {
+	min-width: 0;
+	flex: 1;
+}
+.affiliate-heading p {
+	margin-top: 8px;
+	font-size: 16px;
+}
+.affiliate-nav,
+.affiliate-actions {
+	display: flex;
+	align-items: center;
+	flex-wrap: wrap;
+	gap: 12px;
+}
+.affiliate-nav {
+	border-bottom: 1px solid var(--border, #e2e8f0);
+	gap: 24px;
+	padding-bottom: 12px;
+}
+.affiliate-page a {
+	color: inherit;
+	text-underline-offset: 4px;
+}
+.affiliate-page a:hover {
+	text-decoration: underline;
+}
+.affiliate-nav a {
+	min-height: 44px;
+	display: inline-flex;
+	align-items: center;
+	font-weight: 500;
+}
+.affiliate-muted {
+	color: var(--muted-foreground, #64748b);
+}
+.affiliate-small {
+	font-size: 12px;
+}
+.affiliate-page :is(button, input, textarea, select, .affiliate-primary) {
+	font: inherit;
+	border: 1px solid var(--border, #e2e8f0);
+	border-radius: 6px;
+	min-height: 44px;
+	padding: 10px 12px;
+	color: inherit;
+	background: var(--background, #fff);
+}
+.affiliate-page :is(input, textarea, select) {
+	width: 100%;
+	min-width: 0;
+}
+.affiliate-page textarea {
+	resize: vertical;
+}
+.affiliate-page button {
+	cursor: pointer;
+}
+.affiliate-page button:hover {
+	background: var(--muted, #f1f5f9);
+}
+.affiliate-page :is(button, input, textarea, select):disabled {
+	opacity: 0.6;
+	cursor: default;
+}
+.affiliate-page
+	:is(button, input, textarea, select, a, [tabindex]):focus-visible {
+	outline: 2px solid var(--ring, #2563eb);
+	outline-offset: 3px;
+}
+.affiliate-page .affiliate-primary {
+	display: inline-flex;
+	justify-content: center;
+	align-items: center;
+	background: var(--primary, #2563eb);
+	color: var(--primary-foreground, #fff);
+	border-color: transparent;
+	font-weight: 500;
+	text-decoration: none;
+}
+.affiliate-page .affiliate-primary:hover {
+	background: var(--primary, #2563eb);
+	opacity: 0.9;
+	text-decoration: none;
+}
+.affiliate-page fieldset {
+	padding: 0;
+	margin: 0;
+	border: 0;
+	min-width: 0;
+}
+.affiliate-page fieldset > * + * {
+	margin-top: 20px;
+}
+.affiliate-form-grid {
+	display: grid;
+	grid-template-columns: repeat(2, minmax(0, 1fr));
+	gap: 20px 28px;
+	align-items: start;
+}
+.affiliate-field {
+	display: grid;
+	gap: 8px;
+	min-width: 0;
+}
+.affiliate-field > span:first-child {
+	font-weight: 500;
+}
+.affiliate-stack > * + * {
+	margin-top: 16px;
+}
+.affiliate-panel {
+	padding: 24px;
+	border: 1px solid var(--border, #e2e8f0);
+	border-radius: 8px;
+}
+.affiliate-section {
+	border-top: 1px solid var(--border, #e2e8f0);
+	padding-top: 28px;
+}
+.affiliate-toolbar {
+	display: flex;
+	align-items: end;
+	flex-wrap: wrap;
+	gap: 16px;
+}
+.affiliate-toolbar > .affiliate-field {
+	flex: 1;
+	min-width: min(240px, 100%);
+}
+.affiliate-table-scroll {
+	max-width: 100%;
+	overflow-x: auto;
+}
+.affiliate-page table {
+	width: 100%;
+	border-collapse: collapse;
+	text-align: left;
+	font-variant-numeric: tabular-nums;
+}
+.affiliate-page th,
+.affiliate-page td {
+	padding: 16px;
+	border-bottom: 1px solid var(--border, #e2e8f0);
+	vertical-align: top;
+	max-width: 350px;
+	min-width: 110px;
+	overflow-wrap: anywhere;
+}
+.affiliate-page th {
+	font-weight: 500;
+	font-size: 12px;
+	color: var(--muted-foreground, #64748b);
+}
+.affiliate-page :is(th, td):first-child {
+	padding-left: 0;
+}
+.affiliate-page :is(th, td):last-child {
+	padding-right: 0;
+}
+.affiliate-page td p {
+	margin-top: 5px;
+}
+.affiliate-page .affiliate-number {
+	text-align: right;
+	white-space: nowrap;
+}
+.affiliate-record-link {
+	font-weight: 500;
+}
+.affiliate-status {
+	display: inline-block;
+	padding: 3px 8px;
+	border-radius: 4px;
+	font-size: 12px;
+	font-weight: 500;
+	background: var(--muted, #f1f5f9);
+}
+.affiliate-status:is(
+		[data-status="approved"],
+		[data-status="sent"],
+		[data-status="paid"]
+	) {
+	box-shadow: inset 3px 0 #16a34a;
+	padding-left: 10px;
+}
+.affiliate-status[data-status="pending"] {
+	box-shadow: inset 3px 0 #d97706;
+	padding-left: 10px;
+}
+.affiliate-status:is(
+		[data-status="failed"],
+		[data-status="suspended"],
+		[data-status="voided"]
+	) {
+	box-shadow: inset 3px 0 var(--destructive, #dc2626);
+	padding-left: 10px;
+}
+.affiliate-empty {
+	padding: 32px 0;
+	color: var(--muted-foreground, #64748b);
+}
+.affiliate-metrics {
+	display: flex;
+	flex-wrap: wrap;
+	gap: 24px 64px;
+	margin: 0 0 20px;
+}
+.affiliate-metrics dt {
+	color: var(--muted-foreground, #64748b);
+}
+.affiliate-metrics dd {
+	margin: 4px 0 0;
+	font-size: 30px;
+	font-weight: 600;
+	font-variant-numeric: tabular-nums;
+}
+.affiliate-application {
+	max-width: 760px;
+}
+.affiliate-notice {
+	padding: 16px;
+	border-left: 3px solid var(--border, #e2e8f0);
+	background: var(--muted, #f1f5f9);
+}
+.affiliate-error {
+	color: var(--destructive, #b91c1c);
+}
+.affiliate-assets {
+	list-style: none;
+	padding: 0;
+	margin: 0;
+}
+.affiliate-assets > li {
+	padding: 16px 0;
+	border-bottom: 1px solid var(--border, #e2e8f0);
+}
+.affiliate-assets .affiliate-actions {
+	margin-top: 8px;
+}
+.affiliate-sr-only {
+	position: absolute;
+	width: 1px;
+	height: 1px;
+	padding: 0;
+	margin: -1px;
+	overflow: hidden;
+	clip-path: inset(50%);
+	white-space: nowrap;
+	border: 0;
+}
+@media (max-width: 640px) {
+	.affiliate-page {
+		padding: 24px 16px;
+	}
+	.affiliate-page h1 {
+		font-size: 26px;
+	}
+	.affiliate-form-grid {
+		grid-template-columns: minmax(0, 1fr);
+	}
+	.affiliate-panel {
+		padding: 20px 16px;
+	}
+	.affiliate-nav {
+		gap: 20px;
+	}
+	.affiliate-page th,
+	.affiliate-page td {
+		padding: 12px;
+	}
+}
+
+@source "./**/*.{mjs,cjs}";

package/dist/types.cjs

@@ -0,0 +1,2 @@
+'use strict';
+

package/dist/types.d.cts

@@ -0,0 +1,176 @@
+/** Application review and referral eligibility state. */
+type AffiliateStatus = "pending" | "approved" | "suspended";
+/** Percentage points or a fixed amount in currency minor units. */
+type CommissionType = "percent" | "flat";
+/** Review and settlement state; payouts alone move commissions to paid. */
+type CommissionStatus = "pending" | "approved" | "paid" | "voided";
+/** Manual payment outcome; failed batches release their reserved commissions. */
+type PayoutStatus = "pending" | "sent" | "failed";
+/** Partner profile with ISO timestamp strings and optional administrative notes. */
+interface Affiliate {
+    id: string;
+    /** Authenticated account that exclusively owns this profile's portal. */
+    userId: string;
+    name: string;
+    email: string;
+    code: string;
+    status: AffiliateStatus;
+    /** Payment instructions stored as text, without processor-specific validation. */
+    payoutDetails?: string | null;
+    /** Administrative notes, omitted from portal responses. */
+    notes?: string | null;
+    commissionType?: CommissionType | null;
+    commissionValue?: number | null;
+    createdAt: string;
+    updatedAt: string;
+}
+/** Recorded visit; its stored ISO timestamp determines cookie attribution eligibility. */
+interface ReferralClick {
+    id: string;
+    affiliateId: string;
+    code: string;
+    landingPath?: string | null;
+    referrer?: string | null;
+    /** Optional hash supplied by a trusted integration; HTTP tracking does not collect IPs. */
+    ipHash?: string | null;
+    userAgent?: string | null;
+    createdAt: string;
+}
+/** Attributed order/event with a safe integer amount in currency minor units. */
+interface Conversion {
+    id: string;
+    affiliateId: string;
+    clickId?: string | null;
+    /** Stable order/event identifier used to deduplicate conversion retries. */
+    externalRef?: string | null;
+    amount: number;
+    currency: string;
+    status: "pending" | "approved" | "rejected";
+    createdAt: string;
+}
+/** Earnings from one conversion, expressed in currency minor units with ISO timestamps. */
+interface Commission {
+    id: string;
+    affiliateId: string;
+    conversionId: string;
+    /** Pending or settled payout reservation; empty when available for a new batch. */
+    payoutId?: string | null;
+    amount: number;
+    currency: string;
+    status: CommissionStatus;
+    createdAt: string;
+    updatedAt: string;
+}
+/** One affiliate's manual payment batch in one currency; dates are ISO strings. */
+interface Payout {
+    id: string;
+    affiliateId: string;
+    amount: number;
+    currency: string;
+    status: PayoutStatus;
+    reference?: string | null;
+    paidAt?: string | null;
+    createdAt: string;
+}
+/** Offset pagination and filters for affiliate administration lists. */
+interface ListParams {
+    limit?: number;
+    offset?: number;
+    affiliateId?: string;
+    status?: string;
+    currency?: string;
+}
+/** A page of records and the total count before pagination. */
+interface ListResult<T> {
+    items: T[];
+    total: number;
+    limit: number;
+    offset: number;
+}
+/** Referral counts and commission minor-unit totals, grouped separately per currency. */
+interface AffiliateStats {
+    clicks: number;
+    conversions: number;
+    totals: {
+        currency: string;
+        pending: number;
+        approved: number;
+        paid: number;
+        voided: number;
+    }[];
+}
+/** HTTP(S) landing-page template and optional banner link shown to partners. */
+interface MarketingAsset {
+    name: string;
+    url: string;
+    description?: string;
+    bannerUrl?: string;
+}
+/** One account's profile, totals, recent financial history, and program marketing assets. */
+interface AffiliatePortal {
+    affiliate: Affiliate | null;
+    stats: AffiliateStats;
+    commissions: Commission[];
+    payouts: Payout[];
+    assets: MarketingAsset[];
+}
+/** Pending-profile input; administrators supply ownership, applications use request identity. */
+interface CreateAffiliateInput {
+    userId: string;
+    name: string;
+    email: string;
+    code?: string;
+    payoutDetails?: string;
+}
+/** Administrative profile edits; commission override type and value must be set or cleared together. */
+interface UpdateAffiliateInput {
+    name?: string;
+    email?: string;
+    code?: string;
+    status?: AffiliateStatus;
+    payoutDetails?: string | null;
+    notes?: string | null;
+    commissionType?: CommissionType | null;
+    commissionValue?: number | null;
+}
+/** A referral visit and optional metadata supplied by the tracking transport or trusted caller. */
+interface TrackClickInput {
+    code: string;
+    landingPath?: string;
+    referrer?: string;
+    ipHash?: string;
+    userAgent?: string;
+}
+/** Verified order/event amount and attribution; omitted attribution returns null without a request fallback. */
+interface CreateConversionInput {
+    externalRef?: string;
+    amount: number;
+    currency?: string;
+    attribution?: {
+        code?: string;
+        clickId?: string;
+    };
+}
+/** Reserve selected or all available approved commissions for one affiliate and currency. */
+interface CreatePayoutInput {
+    affiliateId: string;
+    currency: string;
+    commissionIds?: string[];
+}
+/** Attribution window, default commission rule, and optional partner marketing assets. */
+interface AffiliateOptions {
+    /** Trusted HTTP(S) site origin for tracking redirects when the API uses a separate origin. */
+    siteOrigin?: string;
+    /** Number of days a stored referral click remains eligible. Defaults to 30. */
+    attributionWindowDays?: number;
+    /** Whether a new tracked referral replaces the existing cookie. Defaults to last_touch. */
+    attributionMode?: "first_touch" | "last_touch";
+    /** Default commission rule, unless the affiliate has an override. Defaults to percent. */
+    defaultCommissionType?: CommissionType;
+    /** Percentage (up to two decimals) or integer minor units for flat rules. Defaults to 20. */
+    defaultCommissionValue?: number;
+    /** Optional landing page templates and banner metadata displayed in the portal. */
+    marketingAssets?: MarketingAsset[];
+}
+
+export type { Affiliate, AffiliateOptions, AffiliatePortal, AffiliateStats, AffiliateStatus, Commission, CommissionStatus, CommissionType, Conversion, CreateAffiliateInput, CreateConversionInput, CreatePayoutInput, ListParams, ListResult, MarketingAsset, Payout, PayoutStatus, ReferralClick, TrackClickInput, UpdateAffiliateInput };