@soulbatical/tetra-core 0.1.7 → 0.1.9

package/dist/middleware/permissionsMiddleware.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionsMiddleware.d.ts","sourceRoot":"","sources":["../../src/middleware/permissionsMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/middleware/permissionsMiddleware.js

@@ -0,0 +1,237 @@
+/**
+ * @tetra/core — Permissions Middleware (Config-Driven RBAC)
+ *
+ * Controls what a USER can do based on their role within a feature.
+ * This is separate from entitlements (what an ORG can do based on their plan).
+ *
+ * Projects call configurePermissions() once at startup with their feature
+ * permission configs. Each feature defines which roles can create/read/update/delete.
+ *
+ * @example
+ * ```typescript
+ * configurePermissions({
+ *   notes: {
+ *     resource: 'notes',
+ *     roles: {
+ *       admin:  { create: true, read: true, update: true, delete: true },
+ *       coach:  { create: true, read: true, update: 'own',  delete: 'own' },
+ *       client: { create: false, read: true, update: false, delete: false },
+ *     },
+ *     ui: {
+ *       nav: ['admin', 'coach'],
+ *       tabs: { notities: ['admin', 'coach'] },
+ *       actions: { create_note: ['admin', 'coach'] },
+ *     },
+ *   },
+ * });
+ *
+ * // In routes:
+ * router.post('/', requirePermission('notes', 'create'), handler);
+ * router.delete('/:id', requirePermission('notes', 'delete'), handler);
+ * ```
+ */
+import { createLogger } from '../utils/logger.js';
+import { RFC7807ErrorResponse } from '../shared/rfc7807ErrorResponse.js';
+const logger = createLogger('middleware:permissions');
+// ─── State ──────────────────────────────────────────────────
+const permissionConfigs = new Map();
+// ─── Configure ──────────────────────────────────────────────
+/**
+ * Register permission configs for features. Call once at app startup.
+ * Can be called multiple times to add more features.
+ *
+ * @param configs - Map of resource name → FeaturePermissions
+ *
+ * @example
+ * configurePermissions({
+ *   notes: notesPermissions,
+ *   tracks: tracksPermissions,
+ * });
+ */
+export function configurePermissions(configs) {
+    for (const [key, config] of Object.entries(configs)) {
+        permissionConfigs.set(key, config);
+    }
+    logger.info({ features: Object.keys(configs) }, `Permissions configured for ${Object.keys(configs).length} feature(s)`);
+}
+/**
+ * Register a single feature's permissions.
+ */
+export function registerFeaturePermissions(config) {
+    permissionConfigs.set(config.resource, config);
+}
+// ─── Public API ─────────────────────────────────────────────
+/**
+ * Check if a role is allowed to perform an action on a resource.
+ *
+ * Returns the PermissionValue:
+ * - true:   allowed
+ * - false:  denied
+ * - 'own':  allowed with scope restriction
+ * - string: custom scope
+ *
+ * Unknown roles/resources/actions default to false (fail closed).
+ */
+export function checkPermission(resource, action, role) {
+    const config = permissionConfigs.get(resource);
+    if (!config)
+        return false;
+    const rolePerms = config.roles[role];
+    if (!rolePerms)
+        return false;
+    const value = rolePerms[action];
+    // Fallback: 'list' inherits from 'read' if not explicitly defined
+    if (value === undefined && action === 'list') {
+        return rolePerms['read'] ?? false;
+    }
+    return value ?? false;
+}
+/**
+ * Check if a role can see a nav item for a resource.
+ */
+export function canSeeNav(resource, role) {
+    const config = permissionConfigs.get(resource);
+    if (!config?.ui?.nav)
+        return true; // No nav config = visible to all
+    return config.ui.nav.includes(role);
+}
+/**
+ * Check if a role can see a specific tab within a resource.
+ */
+export function canSeeTab(resource, tabId, role) {
+    const config = permissionConfigs.get(resource);
+    if (!config?.ui?.tabs?.[tabId])
+        return true; // No tab config = visible to all
+    return config.ui.tabs[tabId].includes(role);
+}
+/**
+ * Check if a role can perform a specific UI action.
+ */
+export function canDoAction(resource, actionId, role) {
+    const config = permissionConfigs.get(resource);
+    if (!config?.ui?.actions?.[actionId])
+        return true; // No action config = visible to all
+    return config.ui.actions[actionId].includes(role);
+}
+/**
+ * Get all permission configs. Useful for:
+ * - Frontend: GET /api/permissions → returns all UI permissions for the user's role
+ * - Documentation: generate permission matrices
+ */
+export function getAllPermissionConfigs() {
+    return Object.fromEntries(permissionConfigs);
+}
+/**
+ * Get the resolved permissions for a specific role across all features.
+ * Returns only UI-relevant data for the frontend.
+ */
+export function getPermissionsForRole(role) {
+    const result = {};
+    for (const [resource, config] of permissionConfigs) {
+        const rolePerms = config.roles[role] ?? {};
+        result[resource] = {
+            nav: config.ui?.nav ? config.ui.nav.includes(role) : true,
+            tabs: Object.fromEntries(Object.entries(config.ui?.tabs ?? {}).map(([tabId, roles]) => [tabId, roles.includes(role)])),
+            actions: Object.fromEntries(Object.entries(config.ui?.actions ?? {}).map(([actionId, roles]) => [actionId, roles.includes(role)])),
+            crud: {
+                create: rolePerms.create ?? false,
+                read: rolePerms.read ?? false,
+                update: rolePerms.update ?? false,
+                delete: rolePerms.delete ?? false,
+                list: rolePerms.list ?? rolePerms.read ?? false,
+            },
+        };
+    }
+    return result;
+}
+// ─── Middleware ──────────────────────────────────────────────
+/**
+ * Express middleware: require a specific permission on a resource.
+ *
+ * Checks the user's role against the registered permission config.
+ * Superadmins bypass all permission checks.
+ *
+ * When the permission value is 'own' or another scope string,
+ * the middleware allows the request but attaches `req.permissionScope`
+ * so the controller can apply the appropriate filter.
+ *
+ * @param resource - The resource name (must match a registered config)
+ * @param action - The action to check (create, read, update, delete, or custom)
+ *
+ * @example
+ * router.post('/', requirePermission('notes', 'create'), handler);
+ * router.delete('/:id', requirePermission('notes', 'delete'), handler);
+ *
+ * // In controller, check scope:
+ * if (req.permissionScope === 'own') {
+ *   query = query.eq('author_id', req.user.id);
+ * }
+ */
+export function requirePermission(resource, action) {
+    return (req, res, next) => {
+        // Superadmins bypass all permission checks
+        if (req.user?.is_superadmin || req.user?.isSuperAdmin || req.user?.isSuperadmin) {
+            return next();
+        }
+        const role = req.user?.role;
+        if (!role) {
+            return RFC7807ErrorResponse.forbidden(res, 'No role assigned. Cannot check permissions.');
+        }
+        const permission = checkPermission(resource, action, role);
+        if (permission === false) {
+            return res.status(403).json({
+                type: 'about:blank',
+                title: 'Permission denied',
+                detail: `Role "${role}" is not allowed to "${action}" on "${resource}".`,
+                status: 403,
+                instance: req.originalUrl,
+                resource,
+                action,
+                role,
+            });
+        }
+        // If permission is a scope string (e.g., 'own', 'track_member'),
+        // attach it to the request so controllers can filter accordingly.
+        if (typeof permission === 'string') {
+            req.permissionScope = permission;
+        }
+        next();
+    };
+}
+/**
+ * Express middleware: require ANY of the listed permissions.
+ *
+ * @example
+ * router.get('/feed', requireAnyPermission([
+ *   { resource: 'notes', action: 'read' },
+ *   { resource: 'messages', action: 'read' },
+ * ]), handler);
+ */
+export function requireAnyPermission(permissions) {
+    return (req, res, next) => {
+        if (req.user?.is_superadmin || req.user?.isSuperAdmin || req.user?.isSuperadmin) {
+            return next();
+        }
+        const role = req.user?.role;
+        if (!role) {
+            return RFC7807ErrorResponse.forbidden(res, 'No role assigned.');
+        }
+        const hasAny = permissions.some(({ resource, action }) => {
+            const perm = checkPermission(resource, action, role);
+            return perm !== false;
+        });
+        if (!hasAny) {
+            return res.status(403).json({
+                type: 'about:blank',
+                title: 'Permission denied',
+                detail: `Role "${role}" lacks all required permissions.`,
+                status: 403,
+                instance: req.originalUrl,
+                required: permissions,
+                role,
+            });
+        }
+        next();
+    };
+}
+//# sourceMappingURL=permissionsMiddleware.js.map

package/dist/middleware/permissionsMiddleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissionsMiddleware.js","sourceRoot":"","sources":["../../src/middleware/permissionsMiddleware.ts"],"names":[],"mappings":"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"}

package/dist/shared/affiliate/AffiliateAttributionService.d.ts

@@ -0,0 +1,47 @@
+/**
+ * AffiliateAttributionService
+ *
+ * Generic affiliate attribution and commission engine.
+ * Internal referral only (voucher > URL > cookie).
+ * Config-driven tier upgrades.
+ *
+ * @module @soulbatical/tetra-core/affiliate
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+import type { Request } from 'express';
+import type { AffiliateAttribution, AffiliateConfig, AffiliateOrder } from './types.js';
+export declare class AffiliateAttributionService {
+    private supabase;
+    private organizationId?;
+    private config;
+    constructor(supabase: SupabaseClient, config?: Partial<AffiliateConfig>, organizationId?: string);
+    /**
+     * Determine affiliate attribution for an order.
+     * Priority: Voucher > URL (?ref=) > Cookie
+     */
+    determineAttribution(req: Request, voucherCode?: string): Promise<AffiliateAttribution | null>;
+    /**
+     * Create a commission record for an affiliate sale.
+     * Updates affiliate stats and checks for tier upgrade.
+     */
+    createCommission(order: AffiliateOrder, attribution: AffiliateAttribution): Promise<void>;
+    /**
+     * Generate a referral code for a new affiliate.
+     * Uses custom generator from config or default format.
+     */
+    generateReferralCode(contactName: string): string;
+    private checkVoucherAttribution;
+    private checkUrlParameter;
+    private checkCookie;
+    /**
+     * Resolve an affiliate from referral code or ID.
+     */
+    resolveAffiliate(reference: string, affiliateId: string | null): Promise<any>;
+    private updateAffiliateStats;
+    /**
+     * Check if affiliate qualifies for tier upgrade (config-driven).
+     */
+    checkTierUpgrade(affiliateId: string, totalSales: number): Promise<void>;
+    private upgradeAffiliateTier;
+}
+//# sourceMappingURL=AffiliateAttributionService.d.ts.map

package/dist/shared/affiliate/AffiliateAttributionService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AffiliateAttributionService.d.ts","sourceRoot":"","sources":["../../../src/shared/affiliate/AffiliateAttributionService.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,KAAK,EAAE,oBAAoB,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AA0BxF,qBAAa,2BAA2B;IACtC,OAAO,CAAC,QAAQ,CAAiB;IACjC,OAAO,CAAC,cAAc,CAAC,CAAS;IAChC,OAAO,CAAC,MAAM,CAAkB;gBAG9B,QAAQ,EAAE,cAAc,EACxB,MAAM,CAAC,EAAE,OAAO,CAAC,eAAe,CAAC,EACjC,cAAc,CAAC,EAAE,MAAM;IASzB;;;OAGG;IACG,oBAAoB,CACxB,GAAG,EAAE,OAAO,EACZ,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAgCvC;;;OAGG;IACG,gBAAgB,CACpB,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,oBAAoB,GAChC,OAAO,CAAC,IAAI,CAAC;IA6DhB;;;OAGG;IACH,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;YAOnC,uBAAuB;IAwBrC,OAAO,CAAC,iBAAiB;IAYzB,OAAO,CAAC,WAAW;IAiCnB;;OAEG;IACG,gBAAgB,CACpB,SAAS,EAAE,MAAM,EACjB,WAAW,EAAE,MAAM,GAAG,IAAI,GACzB,OAAO,CAAC,GAAG,CAAC;YAkCD,oBAAoB;IAgBlC;;OAEG;IACG,gBAAgB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;YA8ChE,oBAAoB;CAkDnC"}

package/dist/shared/affiliate/AffiliateAttributionService.js

@@ -0,0 +1,308 @@
+import crypto from 'crypto';
+import { createLogger } from '../../utils/logger.js';
+const logger = createLogger('service:affiliate:attribution');
+const DEFAULT_CONFIG = {
+    defaultCommissionPercentage: 30,
+    cookieDurationDays: 90,
+    tiers: [
+        { name: 'starter', minSales: 0, commissionPercentage: 30 },
+        { name: 'active', minSales: 10, commissionPercentage: 35 },
+    ],
+};
+/**
+ * Generate a referral code from a contact name.
+ * Format: firstname-XXXX (e.g., 'monique-1234')
+ */
+function defaultReferralCodeGenerator(contactName) {
+    const normalized = contactName
+        .toLowerCase()
+        .replace(/[^a-z0-9]/g, '')
+        .substring(0, 15);
+    const randomDigits = crypto.randomInt(1000, 10000);
+    return `${normalized}-${randomDigits}`;
+}
+export class AffiliateAttributionService {
+    supabase;
+    organizationId;
+    config;
+    constructor(supabase, config, organizationId) {
+        this.supabase = supabase;
+        this.organizationId = organizationId;
+        this.config = { ...DEFAULT_CONFIG, ...config };
+    }
+    // ─── Attribution ────────────────────────────────────────────
+    /**
+     * Determine affiliate attribution for an order.
+     * Priority: Voucher > URL (?ref=) > Cookie
+     */
+    async determineAttribution(req, voucherCode) {
+        logger.info('Determining affiliate attribution', { voucherCode });
+        // 1. Voucher with affiliate
+        if (voucherCode) {
+            const attribution = await this.checkVoucherAttribution(voucherCode);
+            if (attribution) {
+                logger.info('Attribution via voucher', attribution);
+                return attribution;
+            }
+        }
+        // 2. URL parameter (?ref=)
+        const urlAttribution = this.checkUrlParameter(req);
+        if (urlAttribution) {
+            logger.info('Attribution via URL', urlAttribution);
+            return urlAttribution;
+        }
+        // 3. Cookie fallback
+        const cookieAttribution = this.checkCookie(req);
+        if (cookieAttribution) {
+            logger.info('Attribution via cookie', cookieAttribution);
+            return cookieAttribution;
+        }
+        logger.info('No affiliate attribution found');
+        return null;
+    }
+    // ─── Commission ─────────────────────────────────────────────
+    /**
+     * Create a commission record for an affiliate sale.
+     * Updates affiliate stats and checks for tier upgrade.
+     */
+    async createCommission(order, attribution) {
+        logger.info('Creating commission', { orderId: order.id, attribution });
+        const affiliate = await this.resolveAffiliate(attribution.reference, attribution.affiliate_id);
+        if (!affiliate) {
+            logger.warn('Affiliate not found', { attribution });
+            return;
+        }
+        const orderAmount = order.total_excl_vat;
+        const commissionAmount = orderAmount * (affiliate.commission_percentage / 100);
+        logger.info('Commission calculated', {
+            affiliateId: affiliate.id,
+            orderAmount,
+            commissionPercentage: affiliate.commission_percentage,
+            commissionAmount,
+        });
+        // Create commission record
+        const { data: commission, error } = await this.supabase
+            .from('affiliate_commissions')
+            .insert({
+            organization_id: order.organization_id,
+            affiliate_id: affiliate.id,
+            order_id: order.id,
+            affiliate_source: 'internal',
+            product_name: 'Order',
+            order_amount_excl_vat: orderAmount,
+            commission_percentage: affiliate.commission_percentage,
+            commission_amount: commissionAmount,
+            status: 'pending',
+        })
+            .select()
+            .single();
+        if (error) {
+            logger.error('Failed to create commission', { error, orderId: order.id });
+            throw error;
+        }
+        logger.info('Commission created', { commissionId: commission.id });
+        // Update affiliate stats
+        await this.updateAffiliateStats(affiliate.id, {
+            total_sales: affiliate.total_sales + 1,
+            total_revenue: affiliate.total_revenue + orderAmount,
+            total_commission_earned: affiliate.total_commission_earned + commissionAmount,
+            last_sale_at: new Date().toISOString(),
+        });
+        // Check for tier upgrade
+        await this.checkTierUpgrade(affiliate.id, affiliate.total_sales + 1);
+    }
+    // ─── Referral Code ──────────────────────────────────────────
+    /**
+     * Generate a referral code for a new affiliate.
+     * Uses custom generator from config or default format.
+     */
+    generateReferralCode(contactName) {
+        const generator = this.config.referralCodeGenerator || defaultReferralCodeGenerator;
+        return generator(contactName);
+    }
+    // ─── Private: Attribution Checks ────────────────────────────
+    async checkVoucherAttribution(voucherCode) {
+        try {
+            const { data: voucher, error } = await this.supabase
+                .from('vouchers')
+                .select('id, affiliate_id')
+                .eq('code', voucherCode)
+                .single();
+            if (error || !voucher?.affiliate_id) {
+                return null;
+            }
+            return {
+                affiliate_id: voucher.affiliate_id,
+                source: 'internal',
+                attribution_type: 'voucher',
+                reference: voucherCode,
+            };
+        }
+        catch (error) {
+            logger.error('Error checking voucher attribution', error);
+            return null;
+        }
+    }
+    checkUrlParameter(req) {
+        const ref = req.query.ref;
+        if (!ref)
+            return null;
+        return {
+            affiliate_id: null,
+            source: 'internal',
+            attribution_type: 'url',
+            reference: ref,
+        };
+    }
+    checkCookie(req) {
+        const cookie = req.cookies?.affiliate_ref;
+        if (!cookie)
+            return null;
+        try {
+            const data = JSON.parse(cookie);
+            const age = Date.now() - data.timestamp;
+            const maxAge = this.config.cookieDurationDays * 24 * 60 * 60 * 1000;
+            if (age > maxAge) {
+                logger.info('Affiliate cookie expired', { ageDays: Math.floor(age / (24 * 60 * 60 * 1000)) });
+                return null;
+            }
+            // Only accept internal source in tetra-core
+            if (data.source && data.source !== 'internal') {
+                return null;
+            }
+            return {
+                affiliate_id: null,
+                source: 'internal',
+                attribution_type: 'cookie',
+                reference: data.ref,
+            };
+        }
+        catch (error) {
+            logger.error('Error parsing affiliate cookie', error);
+            return null;
+        }
+    }
+    // ─── Private: Affiliate Resolution ──────────────────────────
+    /**
+     * Resolve an affiliate from referral code or ID.
+     */
+    async resolveAffiliate(reference, affiliateId) {
+        // If affiliate ID already known (voucher attribution)
+        if (affiliateId) {
+            const { data, error } = await this.supabase
+                .from('affiliates')
+                .select('*')
+                .eq('id', affiliateId)
+                .eq('status', 'active')
+                .single();
+            if (error) {
+                logger.error('Failed to fetch affiliate by ID', { error, affiliateId });
+                return null;
+            }
+            return data;
+        }
+        // Look up by referral code
+        const { data, error } = await this.supabase
+            .from('affiliates')
+            .select('*')
+            .eq('referral_code', reference)
+            .eq('status', 'active')
+            .single();
+        if (error) {
+            logger.error('Failed to fetch affiliate by referral code', { error, reference });
+            return null;
+        }
+        return data;
+    }
+    // ─── Private: Stats & Tiers ─────────────────────────────────
+    async updateAffiliateStats(affiliateId, updates) {
+        const { error } = await this.supabase
+            .from('affiliates')
+            .update(updates)
+            .eq('id', affiliateId);
+        if (error) {
+            logger.error('Failed to update affiliate stats', { error, affiliateId });
+            throw error;
+        }
+        logger.info('Affiliate stats updated', { affiliateId, updates });
+    }
+    /**
+     * Check if affiliate qualifies for tier upgrade (config-driven).
+     */
+    async checkTierUpgrade(affiliateId, totalSales) {
+        const { data: affiliate, error } = await this.supabase
+            .from('affiliates')
+            .select('tier, commission_percentage')
+            .eq('id', affiliateId)
+            .single();
+        if (error || !affiliate) {
+            logger.error('Failed to fetch affiliate for tier check', { error, affiliateId });
+            return;
+        }
+        // Find the highest qualifying tier
+        const sortedTiers = [...this.config.tiers].sort((a, b) => b.minSales - a.minSales);
+        const qualifyingTier = sortedTiers.find(t => totalSales >= t.minSales);
+        if (!qualifyingTier || qualifyingTier.name === affiliate.tier) {
+            return; // No upgrade needed
+        }
+        // Check if this is actually an upgrade (not a downgrade)
+        const currentTierIndex = this.config.tiers.findIndex(t => t.name === affiliate.tier);
+        const newTierIndex = this.config.tiers.findIndex(t => t.name === qualifyingTier.name);
+        if (newTierIndex <= currentTierIndex) {
+            return;
+        }
+        logger.info('Tier upgrade triggered', {
+            affiliateId,
+            oldTier: affiliate.tier,
+            newTier: qualifyingTier.name,
+            oldCommission: affiliate.commission_percentage,
+            newCommission: qualifyingTier.commissionPercentage,
+            totalSales,
+        });
+        await this.upgradeAffiliateTier(affiliateId, {
+            old_tier: affiliate.tier,
+            new_tier: qualifyingTier.name,
+            old_commission: affiliate.commission_percentage,
+            new_commission: qualifyingTier.commissionPercentage,
+            reason: 'milestone_reached',
+            triggered_by_sale_count: totalSales,
+        });
+    }
+    async upgradeAffiliateTier(affiliateId, upgrade) {
+        // Update affiliate tier and commission
+        const { error: updateError } = await this.supabase
+            .from('affiliates')
+            .update({
+            tier: upgrade.new_tier,
+            commission_percentage: upgrade.new_commission,
+            updated_at: new Date().toISOString(),
+        })
+            .eq('id', affiliateId);
+        if (updateError) {
+            logger.error('Failed to update affiliate tier', { error: updateError, affiliateId });
+            throw updateError;
+        }
+        // Record in tier history
+        const { error: historyError } = await this.supabase
+            .from('affiliate_tier_history')
+            .insert({
+            affiliate_id: affiliateId,
+            old_tier: upgrade.old_tier,
+            new_tier: upgrade.new_tier,
+            old_commission_percentage: upgrade.old_commission,
+            new_commission_percentage: upgrade.new_commission,
+            reason: upgrade.reason,
+            triggered_by_sale_count: upgrade.triggered_by_sale_count,
+        });
+        if (historyError) {
+            logger.error('Failed to record tier history', { error: historyError, affiliateId });
+            // Don't throw — tier upgrade succeeded even if history failed
+        }
+        logger.info('Tier upgraded successfully', {
+            affiliateId,
+            oldTier: upgrade.old_tier,
+            newTier: upgrade.new_tier,
+        });
+    }
+}
+//# sourceMappingURL=AffiliateAttributionService.js.map

package/dist/shared/affiliate/AffiliateAttributionService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AffiliateAttributionService.js","sourceRoot":"","sources":["../../../src/shared/affiliate/AffiliateAttributionService.ts"],"names":[],"mappings":"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"}

package/dist/shared/affiliate/AffiliateClickService.d.ts

@@ -0,0 +1,35 @@
+/**
+ * AffiliateClickService
+ *
+ * Handles click tracking and conversion marking for the affiliate module.
+ *
+ * @module @soulbatical/tetra-core/affiliate
+ */
+import type { SupabaseClient } from '@supabase/supabase-js';
+export declare class AffiliateClickService {
+    private supabase;
+    constructor(supabase: SupabaseClient);
+    /**
+     * Register an affiliate click event.
+     * Returns the click record ID.
+     */
+    registerClick(data: {
+        affiliate_id?: string | null;
+        organization_id?: string | null;
+        affiliate_source: string;
+        visitor_ip?: string | null;
+        user_agent?: string | null;
+        referrer_url?: string | null;
+        landing_page?: string | null;
+        external_click_ref?: string | null;
+    }): Promise<string | null>;
+    /**
+     * Increment affiliate total_clicks counter.
+     */
+    incrementClickCount(affiliateId: string): Promise<void>;
+    /**
+     * Mark a click as converted after a successful order.
+     */
+    markConverted(clickId: string, orderId: string): Promise<void>;
+}
+//# sourceMappingURL=AffiliateClickService.d.ts.map