@btst/plugin-affiliate 0.0.0-stage → 1.0.0

package/dist/api/index.d.ts

@@ -0,0 +1,975 @@
+import * as _btst_stack_plugins_api from '@btst/stack/plugins/api';
+import { DeepReadonly } from '@btst/stack/plugins/api';
+import * as _btst_stack_authorization from '@btst/stack/authorization';
+import * as better_call from 'better-call';
+import { z } from 'zod';
+import { AffiliateOptions, Affiliate, Conversion, Commission, CreatePayoutInput, Payout, AffiliateStatus, CommissionType, CommissionStatus, PayoutStatus, ListParams, AffiliateStats, MarketingAsset, AffiliatePortal, ReferralClick, ListResult, CreateAffiliateInput, CreateConversionInput, TrackClickInput, UpdateAffiliateInput } from '../types.js';
+import * as _btst_db from '@btst/db';
+import { DBAdapter } from '@btst/db';
+export { affiliatePermissions } from '../permissions.js';
+export { AFFILIATE_COOKIE_NAME, attributionFromRequest, createReferralLink, createTrackingLink, getReferralRedirect, isClickWithinWindow, referralCodeFromURL, safeLandingPath, selectAttributionClick } from '../attribution.js';
+
+/** Authorized request context shared by affiliate lifecycle callbacks. */
+interface AffiliateHookContext {
+    readonly request?: Request;
+    readonly identity: {
+        readonly id: string;
+    } | null;
+}
+/** Lifecycle callbacks run after the operation permission is authorized. */
+interface AffiliatePluginHooks {
+    onBeforeApproveAffiliate?: (affiliate: DeepReadonly<Affiliate>, context: AffiliateHookContext) => Promise<void> | void;
+    onAfterConversion?: (conversion: DeepReadonly<Conversion>, commission: DeepReadonly<Commission>, context: AffiliateHookContext) => Promise<void> | void;
+    onBeforePayout?: (batch: DeepReadonly<CreatePayoutInput>, context: AffiliateHookContext) => Promise<void> | void;
+    onAfterPayout?: (payout: DeepReadonly<Payout>, context: AffiliateHookContext) => Promise<void> | void;
+}
+/** Affiliate attribution, commission rules, marketing assets, and lifecycle callbacks. */
+interface AffiliateBackendOptions extends AffiliateOptions {
+    hooks?: AffiliatePluginHooks;
+}
+/** Processor-independent affiliate operations and identity-scoped portal API. */
+declare const affiliateBackendPlugin: (options?: AffiliateBackendOptions) => _btst_stack_plugins_api.BackendPlugin<{
+    listAffiliates: better_call.StrictEndpoint<"/affiliate/affiliates", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            limit?: unknown;
+            offset?: unknown;
+            status?: "pending" | "approved" | "suspended" | undefined;
+        }, {
+            limit?: unknown;
+            offset?: unknown;
+            status?: "pending" | "approved" | "suspended" | undefined;
+        }>;
+    }, {
+        readonly items: readonly {
+            readonly id: string;
+            readonly userId: string;
+            readonly name: string;
+            readonly email: string;
+            readonly code: string;
+            readonly status: AffiliateStatus;
+            readonly payoutDetails?: string | null | undefined;
+            readonly notes?: string | null | undefined;
+            readonly commissionType?: (CommissionType | null) | undefined;
+            readonly commissionValue?: number | null | undefined;
+            readonly createdAt: string;
+            readonly updatedAt: string;
+        }[];
+        readonly total: number;
+        readonly limit: number;
+        readonly offset: number;
+    }>;
+    getAffiliate: better_call.StrictEndpoint<"/affiliate/affiliates/:id", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    }, {
+        readonly affiliate: {
+            readonly id: string;
+            readonly userId: string;
+            readonly name: string;
+            readonly email: string;
+            readonly code: string;
+            readonly status: AffiliateStatus;
+            readonly payoutDetails?: string | null | undefined;
+            readonly notes?: string | null | undefined;
+            readonly commissionType?: (CommissionType | null) | undefined;
+            readonly commissionValue?: number | null | undefined;
+            readonly createdAt: string;
+            readonly updatedAt: string;
+        };
+        readonly stats: {
+            readonly clicks: number;
+            readonly conversions: number;
+            readonly totals: readonly {
+                readonly currency: string;
+                readonly pending: number;
+                readonly approved: number;
+                readonly paid: number;
+                readonly voided: number;
+            }[];
+        };
+    }>;
+    createAffiliate: better_call.StrictEndpoint<"/affiliate/affiliates", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            name: string;
+            email: string;
+            userId: string;
+            code?: string | undefined;
+            payoutDetails?: string | undefined;
+        }, {
+            name: string;
+            email: string;
+            userId: string;
+            code?: string | undefined;
+            payoutDetails?: string | undefined;
+        }>;
+    }, {
+        readonly id: string;
+        readonly userId: string;
+        readonly name: string;
+        readonly email: string;
+        readonly code: string;
+        readonly status: AffiliateStatus;
+        readonly payoutDetails?: string | null | undefined;
+        readonly notes?: string | null | undefined;
+        readonly commissionType?: (CommissionType | null) | undefined;
+        readonly commissionValue?: number | null | undefined;
+        readonly createdAt: string;
+        readonly updatedAt: string;
+    }>;
+    updateAffiliate: better_call.StrictEndpoint<"/affiliate/affiliates/:id", {
+        requireRequest: true;
+    } & {
+        method: "PUT";
+        body: better_call.StandardSchemaV1<{
+            name?: string | undefined;
+            email?: string | undefined;
+            code?: string | undefined;
+            payoutDetails?: string | null | undefined;
+            status?: "pending" | "approved" | "suspended" | undefined;
+            notes?: string | null | undefined;
+            commissionType?: "flat" | "percent" | null | undefined;
+            commissionValue?: number | null | undefined;
+        }, {
+            name?: string | undefined;
+            email?: string | undefined;
+            code?: string | undefined;
+            payoutDetails?: string | null | undefined;
+            status?: "pending" | "approved" | "suspended" | undefined;
+            notes?: string | null | undefined;
+            commissionType?: "flat" | "percent" | null | undefined;
+            commissionValue?: number | null | undefined;
+        }>;
+    }, {
+        readonly id: string;
+        readonly userId: string;
+        readonly name: string;
+        readonly email: string;
+        readonly code: string;
+        readonly status: AffiliateStatus;
+        readonly payoutDetails?: string | null | undefined;
+        readonly notes?: string | null | undefined;
+        readonly commissionType?: (CommissionType | null) | undefined;
+        readonly commissionValue?: number | null | undefined;
+        readonly createdAt: string;
+        readonly updatedAt: string;
+    }>;
+    deleteAffiliate: better_call.StrictEndpoint<"/affiliate/affiliates/:id", {
+        requireRequest: true;
+    } & {
+        method: "DELETE";
+        body: better_call.StandardSchemaV1<unknown, unknown>;
+    }, {
+        readonly success: true;
+    }>;
+    apply: better_call.StrictEndpoint<"/affiliate/apply", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            name: string;
+            email: string;
+            code?: string | undefined;
+            payoutDetails?: string | undefined;
+        }, {
+            name: string;
+            email: string;
+            code?: string | undefined;
+            payoutDetails?: string | undefined;
+        }>;
+    }, {
+        readonly id: string;
+        readonly userId: string;
+        readonly name: string;
+        readonly email: string;
+        readonly code: string;
+        readonly status: AffiliateStatus;
+        readonly payoutDetails?: string | null | undefined;
+        readonly notes?: string | null | undefined;
+        readonly commissionType?: (CommissionType | null) | undefined;
+        readonly commissionValue?: number | null | undefined;
+        readonly createdAt: string;
+        readonly updatedAt: string;
+    }>;
+    getPortal: better_call.StrictEndpoint<"/affiliate/portal", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    }, {
+        readonly affiliate: {
+            readonly id: string;
+            readonly userId: string;
+            readonly name: string;
+            readonly email: string;
+            readonly code: string;
+            readonly status: AffiliateStatus;
+            readonly payoutDetails?: string | null | undefined;
+            readonly notes?: string | null | undefined;
+            readonly commissionType?: (CommissionType | null) | undefined;
+            readonly commissionValue?: number | null | undefined;
+            readonly createdAt: string;
+            readonly updatedAt: string;
+        } | null;
+        readonly stats: {
+            readonly clicks: number;
+            readonly conversions: number;
+            readonly totals: readonly {
+                readonly currency: string;
+                readonly pending: number;
+                readonly approved: number;
+                readonly paid: number;
+                readonly voided: number;
+            }[];
+        };
+        readonly commissions: readonly {
+            readonly id: string;
+            readonly affiliateId: string;
+            readonly conversionId: string;
+            readonly payoutId?: string | null | undefined;
+            readonly amount: number;
+            readonly currency: string;
+            readonly status: CommissionStatus;
+            readonly createdAt: string;
+            readonly updatedAt: string;
+        }[];
+        readonly payouts: readonly {
+            readonly id: string;
+            readonly affiliateId: string;
+            readonly amount: number;
+            readonly currency: string;
+            readonly status: PayoutStatus;
+            readonly reference?: string | null | undefined;
+            readonly paidAt?: string | null | undefined;
+            readonly createdAt: string;
+        }[];
+        readonly assets: readonly {
+            readonly name: string;
+            readonly url: string;
+            readonly description?: string | undefined;
+            readonly bannerUrl?: string | undefined;
+        }[];
+    }>;
+    updatePortal: better_call.StrictEndpoint<"/affiliate/portal", {
+        requireRequest: true;
+    } & {
+        method: "PUT";
+        body: better_call.StandardSchemaV1<{
+            name?: string | undefined;
+            email?: string | undefined;
+            code?: string | undefined;
+            payoutDetails?: string | null | undefined;
+        }, {
+            name?: string | undefined;
+            email?: string | undefined;
+            code?: string | undefined;
+            payoutDetails?: string | null | undefined;
+        }>;
+    }, {
+        readonly id: string;
+        readonly userId: string;
+        readonly name: string;
+        readonly email: string;
+        readonly code: string;
+        readonly status: AffiliateStatus;
+        readonly payoutDetails?: string | null | undefined;
+        readonly commissionType?: (CommissionType | null) | undefined;
+        readonly commissionValue?: number | null | undefined;
+        readonly createdAt: string;
+        readonly updatedAt: string;
+    }>;
+    trackClick: better_call.StrictEndpoint<"/affiliate/track/:code", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            to?: string | undefined;
+        }, {
+            to?: string | undefined;
+        }>;
+    }, Response>;
+    createConversion: better_call.StrictEndpoint<"/affiliate/conversions", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            amount: number;
+            externalRef?: string | undefined;
+            currency?: string | undefined;
+            attribution?: {
+                code?: string | undefined;
+                clickId?: string | undefined;
+            } | undefined;
+        }, {
+            amount: number;
+            externalRef?: string | undefined;
+            currency?: string | undefined;
+            attribution?: {
+                code?: string | undefined;
+                clickId?: string | undefined;
+            } | undefined;
+        }>;
+    }, {
+        readonly conversion: {
+            readonly id: string;
+            readonly affiliateId: string;
+            readonly clickId?: string | null | undefined;
+            readonly externalRef?: string | null | undefined;
+            readonly amount: number;
+            readonly currency: string;
+            readonly status: "pending" | "approved" | "rejected";
+            readonly createdAt: string;
+        };
+        readonly commission: {
+            readonly id: string;
+            readonly affiliateId: string;
+            readonly conversionId: string;
+            readonly payoutId?: string | null | undefined;
+            readonly amount: number;
+            readonly currency: string;
+            readonly status: CommissionStatus;
+            readonly createdAt: string;
+            readonly updatedAt: string;
+        };
+    } | null>;
+    listCommissions: better_call.StrictEndpoint<"/affiliate/commissions", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            limit?: unknown;
+            offset?: unknown;
+            affiliateId?: string | undefined;
+            status?: string | undefined;
+            currency?: string | undefined;
+        }, {
+            limit?: unknown;
+            offset?: unknown;
+            affiliateId?: string | undefined;
+            status?: string | undefined;
+            currency?: string | undefined;
+        }>;
+    }, {
+        readonly items: readonly {
+            readonly id: string;
+            readonly affiliateId: string;
+            readonly conversionId: string;
+            readonly payoutId?: string | null | undefined;
+            readonly amount: number;
+            readonly currency: string;
+            readonly status: CommissionStatus;
+            readonly createdAt: string;
+            readonly updatedAt: string;
+        }[];
+        readonly total: number;
+        readonly limit: number;
+        readonly offset: number;
+    }>;
+    updateCommission: better_call.StrictEndpoint<"/affiliate/commissions/:id", {
+        requireRequest: true;
+    } & {
+        method: "PUT";
+        body: better_call.StandardSchemaV1<{
+            status: "approved" | "voided";
+        }, {
+            status: "approved" | "voided";
+        }>;
+    }, {
+        readonly id: string;
+        readonly affiliateId: string;
+        readonly conversionId: string;
+        readonly payoutId?: string | null | undefined;
+        readonly amount: number;
+        readonly currency: string;
+        readonly status: CommissionStatus;
+        readonly createdAt: string;
+        readonly updatedAt: string;
+    }>;
+    listPayouts: better_call.StrictEndpoint<"/affiliate/payouts", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            limit?: unknown;
+            offset?: unknown;
+            affiliateId?: string | undefined;
+            status?: string | undefined;
+            currency?: string | undefined;
+        }, {
+            limit?: unknown;
+            offset?: unknown;
+            affiliateId?: string | undefined;
+            status?: string | undefined;
+            currency?: string | undefined;
+        }>;
+    }, {
+        readonly items: readonly {
+            readonly id: string;
+            readonly affiliateId: string;
+            readonly amount: number;
+            readonly currency: string;
+            readonly status: PayoutStatus;
+            readonly reference?: string | null | undefined;
+            readonly paidAt?: string | null | undefined;
+            readonly createdAt: string;
+        }[];
+        readonly total: number;
+        readonly limit: number;
+        readonly offset: number;
+    }>;
+    createPayout: better_call.StrictEndpoint<"/affiliate/payouts", {
+        requireRequest: true;
+    } & {
+        method: "POST";
+        body: better_call.StandardSchemaV1<{
+            affiliateId: string;
+            currency: string;
+            commissionIds?: string[] | undefined;
+        }, {
+            affiliateId: string;
+            currency: string;
+            commissionIds?: string[] | undefined;
+        }>;
+    }, {
+        readonly id: string;
+        readonly affiliateId: string;
+        readonly amount: number;
+        readonly currency: string;
+        readonly status: PayoutStatus;
+        readonly reference?: string | null | undefined;
+        readonly paidAt?: string | null | undefined;
+        readonly createdAt: string;
+    }>;
+    updatePayout: better_call.StrictEndpoint<"/affiliate/payouts/:id", {
+        requireRequest: true;
+    } & {
+        method: "PUT";
+        body: better_call.StandardSchemaV1<{
+            status: "sent" | "failed";
+            reference?: string | undefined;
+        }, {
+            status: "sent" | "failed";
+            reference?: string | undefined;
+        }>;
+    }, {
+        readonly id: string;
+        readonly affiliateId: string;
+        readonly amount: number;
+        readonly currency: string;
+        readonly status: PayoutStatus;
+        readonly reference?: string | null | undefined;
+        readonly paidAt?: string | null | undefined;
+        readonly createdAt: string;
+    }>;
+    exportPayouts: better_call.StrictEndpoint<"/affiliate/payouts/export", {
+        requireRequest: true;
+    } & {
+        method: "GET";
+    } & {
+        query: better_call.StandardSchemaV1<{
+            limit?: unknown;
+            offset?: unknown;
+            affiliateId?: string | undefined;
+            status?: string | undefined;
+            currency?: string | undefined;
+        }, {
+            limit?: unknown;
+            offset?: unknown;
+            affiliateId?: string | undefined;
+            status?: string | undefined;
+            currency?: string | undefined;
+        }>;
+    }, {
+        readonly csv: string;
+    }>;
+}, never, {
+    listAffiliates: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        status: z.ZodOptional<z.ZodEnum<{
+            pending: "pending";
+            approved: "approved";
+            suspended: "suspended";
+        }>>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:affiliate.read", z.ZodDiscriminatedUnion<[z.ZodObject<{
+        scope: z.ZodLiteral<"collection">;
+    }, z.core.$strip>, z.ZodObject<{
+        scope: z.ZodLiteral<"record">;
+        affiliateId: z.ZodString;
+    }, z.core.$strip>], "scope">>, {
+        items: {
+            id: string;
+            userId: string;
+            name: string;
+            email: string;
+            code: string;
+            status: AffiliateStatus;
+            payoutDetails?: string | null;
+            notes?: string | null;
+            commissionType?: CommissionType | null;
+            commissionValue?: number | null;
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        total: number;
+        limit: number;
+        offset: number;
+    }, false>;
+    getAffiliate: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:affiliate.read", z.ZodDiscriminatedUnion<[z.ZodObject<{
+        scope: z.ZodLiteral<"collection">;
+    }, z.core.$strip>, z.ZodObject<{
+        scope: z.ZodLiteral<"record">;
+        affiliateId: z.ZodString;
+    }, z.core.$strip>], "scope">>, {
+        affiliate: {
+            id: string;
+            userId: string;
+            name: string;
+            email: string;
+            code: string;
+            status: AffiliateStatus;
+            payoutDetails?: string | null;
+            notes?: string | null;
+            commissionType?: CommissionType | null;
+            commissionValue?: number | null;
+            createdAt: string;
+            updatedAt: string;
+        };
+        stats: {
+            clicks: number;
+            conversions: number;
+            totals: {
+                currency: string;
+                pending: number;
+                approved: number;
+                paid: number;
+                voided: number;
+            }[];
+        };
+    }, false>;
+    createAffiliate: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodEmail;
+        code: z.ZodOptional<z.ZodString>;
+        payoutDetails: z.ZodOptional<z.ZodString>;
+        userId: z.ZodString;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:affiliate.create", undefined>, {
+        id: string;
+        userId: string;
+        name: string;
+        email: string;
+        code: string;
+        status: AffiliateStatus;
+        payoutDetails?: string | null;
+        notes?: string | null;
+        commissionType?: CommissionType | null;
+        commissionValue?: number | null;
+        createdAt: string;
+        updatedAt: string;
+    }, false>;
+    updateAffiliate: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        id: z.ZodString;
+        data: z.ZodObject<{
+            name: z.ZodOptional<z.ZodString>;
+            email: z.ZodOptional<z.ZodEmail>;
+            code: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+            payoutDetails: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            status: z.ZodOptional<z.ZodEnum<{
+                pending: "pending";
+                approved: "approved";
+                suspended: "suspended";
+            }>>;
+            notes: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            commissionType: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+                flat: "flat";
+                percent: "percent";
+            }>>>;
+            commissionValue: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:affiliate.update", z.ZodObject<{
+        affiliateId: z.ZodString;
+        userId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            approved: "approved";
+            suspended: "suspended";
+        }>;
+    }, z.core.$strip>>, {
+        id: string;
+        userId: string;
+        name: string;
+        email: string;
+        code: string;
+        status: AffiliateStatus;
+        payoutDetails?: string | null;
+        notes?: string | null;
+        commissionType?: CommissionType | null;
+        commissionValue?: number | null;
+        createdAt: string;
+        updatedAt: string;
+    }, false>;
+    deleteAffiliate: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        id: z.ZodString;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:affiliate.delete", z.ZodObject<{
+        affiliateId: z.ZodString;
+        userId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            approved: "approved";
+            suspended: "suspended";
+        }>;
+    }, z.core.$strip>>, {
+        success: true;
+    }, false>;
+    apply: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        name: z.ZodString;
+        email: z.ZodEmail;
+        code: z.ZodOptional<z.ZodString>;
+        payoutDetails: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:application.create", undefined>, {
+        id: string;
+        userId: string;
+        name: string;
+        email: string;
+        code: string;
+        status: AffiliateStatus;
+        payoutDetails?: string | null;
+        notes?: string | null;
+        commissionType?: CommissionType | null;
+        commissionValue?: number | null;
+        createdAt: string;
+        updatedAt: string;
+    }, false>;
+    getPortal: _btst_stack_plugins_api.Operation<z.ZodObject<{}, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:portal.read", undefined>, {
+        affiliate: {
+            id: string;
+            userId: string;
+            name: string;
+            email: string;
+            code: string;
+            status: AffiliateStatus;
+            payoutDetails?: string | null;
+            notes?: string | null;
+            commissionType?: CommissionType | null;
+            commissionValue?: number | null;
+            createdAt: string;
+            updatedAt: string;
+        } | null;
+        stats: {
+            clicks: number;
+            conversions: number;
+            totals: {
+                currency: string;
+                pending: number;
+                approved: number;
+                paid: number;
+                voided: number;
+            }[];
+        };
+        commissions: {
+            id: string;
+            affiliateId: string;
+            conversionId: string;
+            payoutId?: string | null;
+            amount: number;
+            currency: string;
+            status: CommissionStatus;
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        payouts: {
+            id: string;
+            affiliateId: string;
+            amount: number;
+            currency: string;
+            status: PayoutStatus;
+            reference?: string | null;
+            paidAt?: string | null;
+            createdAt: string;
+        }[];
+        assets: {
+            name: string;
+            url: string;
+            description?: string;
+            bannerUrl?: string;
+        }[];
+    }, false>;
+    updatePortal: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        name: z.ZodOptional<z.ZodString>;
+        email: z.ZodOptional<z.ZodEmail>;
+        code: z.ZodOptional<z.ZodOptional<z.ZodString>>;
+        payoutDetails: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:portal.update", undefined>, {
+        id: string;
+        userId: string;
+        name: string;
+        email: string;
+        code: string;
+        status: AffiliateStatus;
+        payoutDetails?: string | null;
+        commissionType?: CommissionType | null;
+        commissionValue?: number | null;
+        createdAt: string;
+        updatedAt: string;
+    }, false>;
+    trackClick: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        code: z.ZodString;
+        landingPath: z.ZodOptional<z.ZodString>;
+        referrer: z.ZodOptional<z.ZodString>;
+        ipHash: z.ZodOptional<z.ZodString>;
+        userAgent: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:tracking.track", undefined>, Response, true>;
+    createConversion: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        externalRef: z.ZodOptional<z.ZodString>;
+        amount: z.ZodNumber;
+        currency: z.ZodDefault<z.ZodString>;
+        attribution: z.ZodOptional<z.ZodObject<{
+            code: z.ZodOptional<z.ZodString>;
+            clickId: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:conversion.create", undefined>, {
+        conversion: {
+            id: string;
+            affiliateId: string;
+            clickId?: string | null;
+            externalRef?: string | null;
+            amount: number;
+            currency: string;
+            status: "pending" | "approved" | "rejected";
+            createdAt: string;
+        };
+        commission: {
+            id: string;
+            affiliateId: string;
+            conversionId: string;
+            payoutId?: string | null;
+            amount: number;
+            currency: string;
+            status: CommissionStatus;
+            createdAt: string;
+            updatedAt: string;
+        };
+    } | null, false>;
+    listCommissions: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        affiliateId: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:commission.read", undefined>, {
+        items: {
+            id: string;
+            affiliateId: string;
+            conversionId: string;
+            payoutId?: string | null;
+            amount: number;
+            currency: string;
+            status: CommissionStatus;
+            createdAt: string;
+            updatedAt: string;
+        }[];
+        total: number;
+        limit: number;
+        offset: number;
+    }, false>;
+    updateCommission: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        id: z.ZodString;
+        data: z.ZodObject<{
+            status: z.ZodEnum<{
+                approved: "approved";
+                voided: "voided";
+            }>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:commission.update", z.ZodObject<{
+        commissionId: z.ZodString;
+        affiliateId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            approved: "approved";
+            paid: "paid";
+            voided: "voided";
+        }>;
+    }, z.core.$strip>>, {
+        id: string;
+        affiliateId: string;
+        conversionId: string;
+        payoutId?: string | null;
+        amount: number;
+        currency: string;
+        status: CommissionStatus;
+        createdAt: string;
+        updatedAt: string;
+    }, false>;
+    listPayouts: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        affiliateId: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:payout.read", undefined>, {
+        items: {
+            id: string;
+            affiliateId: string;
+            amount: number;
+            currency: string;
+            status: PayoutStatus;
+            reference?: string | null;
+            paidAt?: string | null;
+            createdAt: string;
+        }[];
+        total: number;
+        limit: number;
+        offset: number;
+    }, false>;
+    createPayout: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        affiliateId: z.ZodString;
+        currency: z.ZodString;
+        commissionIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:payout.create", z.ZodObject<{
+        affiliateId: z.ZodString;
+        currency: z.ZodString;
+    }, z.core.$strip>>, {
+        id: string;
+        affiliateId: string;
+        amount: number;
+        currency: string;
+        status: PayoutStatus;
+        reference?: string | null;
+        paidAt?: string | null;
+        createdAt: string;
+    }, false>;
+    updatePayout: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        id: z.ZodString;
+        data: z.ZodObject<{
+            status: z.ZodEnum<{
+                sent: "sent";
+                failed: "failed";
+            }>;
+            reference: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:payout.update", z.ZodObject<{
+        payoutId: z.ZodString;
+        affiliateId: z.ZodString;
+        status: z.ZodEnum<{
+            pending: "pending";
+            sent: "sent";
+            failed: "failed";
+        }>;
+    }, z.core.$strip>>, {
+        id: string;
+        affiliateId: string;
+        amount: number;
+        currency: string;
+        status: PayoutStatus;
+        reference?: string | null;
+        paidAt?: string | null;
+        createdAt: string;
+    }, false>;
+    exportPayouts: _btst_stack_plugins_api.Operation<z.ZodObject<{
+        limit: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        offset: z.ZodOptional<z.ZodCoercedNumber<unknown>>;
+        affiliateId: z.ZodOptional<z.ZodString>;
+        status: z.ZodOptional<z.ZodString>;
+        currency: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>, _btst_stack_authorization.PermissionDescriptor<"affiliate:payout.export", undefined>, {
+        csv: string;
+    }, false>;
+}, "affiliate">;
+type AffiliateApiRouter = ReturnType<ReturnType<typeof affiliateBackendPlugin>["routes"]>;
+
+declare const affiliateSchema: _btst_db.DbPlugin;
+
+/**
+ * Lower-level reads do not authorize callers or run operation lifecycle hooks.
+ * Callers own input validation and access control; use stack operations for requests.
+ */
+
+/** Adapter reads shared by ordinary callers and an existing transaction. */
+type AffiliateDataAdapter = Omit<DBAdapter, "transaction">;
+type Where = {
+    field: string;
+    value: string;
+    operator: "eq";
+}[];
+/** Normalize adapter Date values for JSON and hydrated query caches. */
+declare function serializeAffiliateRecord<T>(record: unknown): T;
+/** Read an affiliate profile, including administrative notes, by its record ID. */
+declare const getAffiliate: (adapter: AffiliateDataAdapter, id: string) => Promise<Affiliate | null>;
+/** Find the profile owned by an authenticated account ID. */
+declare const getAffiliateByUserId: (adapter: AffiliateDataAdapter, userId: string) => Promise<Affiliate | null>;
+/** Resolve a public referral code without filtering the affiliate's status. */
+declare const getAffiliateByCode: (adapter: AffiliateDataAdapter, code: string) => Promise<Affiliate | null>;
+/** Resolve an opaque click ID; callers must still check its attribution window. */
+declare const getReferralClick: (adapter: AffiliateDataAdapter, id: string) => Promise<ReferralClick | null>;
+/** Read a commission and its payout reservation, if any. */
+declare const getCommission: (adapter: AffiliateDataAdapter, id: string) => Promise<Commission | null>;
+/** Read a manual payout batch by ID. */
+declare const getPayout: (adapter: AffiliateDataAdapter, id: string) => Promise<Payout | null>;
+/** Find an existing order/event conversion for retry deduplication. */
+declare const getConversionByExternalRef: (adapter: AffiliateDataAdapter, externalRef: string) => Promise<Conversion | null>;
+/** Page affiliate profiles, including administrative notes, newest first. */
+declare const listAffiliates: (adapter: AffiliateDataAdapter, params?: ListParams) => Promise<ListResult<Affiliate>>;
+/** Page commissions, optionally filtering affiliate, status, and currency. */
+declare const listCommissions: (adapter: AffiliateDataAdapter, params?: ListParams) => Promise<ListResult<Commission>>;
+/** Page payout batches, optionally filtering affiliate, status, and currency. */
+declare const listPayouts: (adapter: AffiliateDataAdapter, params?: ListParams) => Promise<ListResult<Payout>>;
+/** Read every matching record in stable ID order, beyond adapter page limits. */
+declare function allRows<T>(adapter: AffiliateDataAdapter, model: string, where?: Where): Promise<T[]>;
+/** Count referral activity and total commission minor units separately per currency. */
+declare function getAffiliateStats(adapter: AffiliateDataAdapter, affiliateId: string): Promise<AffiliateStats>;
+/** Read one account's portal, excluding notes and limiting each history to 100 records. */
+declare function getPortal(adapter: AffiliateDataAdapter, userId: string, assets?: MarketingAsset[]): Promise<AffiliatePortal>;
+/** Export all matching batches with quoted cells and escaped spreadsheet formulas. */
+declare function exportPayouts(adapter: AffiliateDataAdapter, params?: ListParams): Promise<string>;
+
+/**
+ * Lower-level writes validate domain inputs but do not authorize callers or run
+ * operation lifecycle hooks. Callers own those concerns; use stack operations for requests.
+ */
+
+type AffiliateSnapshot = Pick<Affiliate, "id" | "userId" | "status">;
+/** Serialize ledger changes with a transactional affiliate row lock and a memory-adapter queue. */
+declare function withAffiliateTransaction<T>(adapter: DBAdapter, affiliateId: string | null, run: (tx: AffiliateDataAdapter) => Promise<T>): Promise<T>;
+/** Create a pending profile with unique account, email, and referral code. */
+declare function createAffiliate(adapter: DBAdapter, input: CreateAffiliateInput): Promise<Affiliate>;
+/** Update a profile while enforcing unique fields, status transitions, and commission rules. */
+declare function updateAffiliate(adapter: DBAdapter, id: string, input: UpdateAffiliateInput, expected?: AffiliateSnapshot): Promise<Affiliate>;
+/** Delete a profile and its clicks only when no financial history exists. */
+declare function deleteAffiliate(adapter: DBAdapter, id: string, expected?: AffiliateSnapshot): Promise<{
+    success: true;
+}>;
+/** Record a local landing-page visit for an approved affiliate. */
+declare function trackClick(adapter: DBAdapter, input: TrackClickInput): Promise<ReferralClick>;
+/** Atomically create an attributed conversion and commission, deduplicating stable external references. */
+declare function createConversion(adapter: DBAdapter, input: CreateConversionInput, options?: AffiliateOptions): Promise<{
+    conversion: Conversion;
+    commission: Commission;
+} | null>;
+/** Approve or void an unsettled commission that has no payout reservation. */
+declare function updateCommission(adapter: DBAdapter, id: string, input: {
+    status: "approved" | "voided";
+}, expected?: Pick<Commission, "id" | "affiliateId" | "status">): Promise<Commission>;
+/** Reserve approved commissions in one currency for a manual payout batch. */
+declare function createPayout(adapter: DBAdapter, input: CreatePayoutInput): Promise<Payout>;
+/** Mark a pending batch sent and its commissions paid, or failed and release its reservations. */
+declare function updatePayout(adapter: DBAdapter, id: string, input: {
+    status: "sent" | "failed";
+    reference?: string;
+}, expected?: Pick<Payout, "id" | "affiliateId" | "status">): Promise<Payout>;
+
+/** Amounts are integer minor units; percentage values may have up to two decimals. */
+declare function calculateCommission(amount: number, type: CommissionType, value: number): number;
+
+export { Affiliate, AffiliateOptions, AffiliatePortal, AffiliateStats, AffiliateStatus, Commission, CommissionStatus, CommissionType, Conversion, CreateAffiliateInput, CreateConversionInput, CreatePayoutInput, ListParams, ListResult, MarketingAsset, Payout, PayoutStatus, ReferralClick, TrackClickInput, UpdateAffiliateInput, affiliateBackendPlugin, affiliateSchema, allRows, calculateCommission, createAffiliate, createConversion, createPayout, deleteAffiliate, exportPayouts, getAffiliate, getAffiliateByCode, getAffiliateByUserId, getAffiliateStats, getCommission, getConversionByExternalRef, getPayout, getPortal, getReferralClick, listAffiliates, listCommissions, listPayouts, serializeAffiliateRecord, trackClick, updateAffiliate, updateCommission, updatePayout, withAffiliateTransaction };
+export type { AffiliateApiRouter, AffiliateBackendOptions, AffiliateDataAdapter, AffiliateHookContext, AffiliatePluginHooks };