+
Analytics
-
-
+
+
-
-
+
+
+
+
-
-
+
+
-
+
- {/* Risk Signals Table */}
-
- {risks.map((risk) => (
- {
- const col = RISK_SIGNAL_COLUMNS.find((c) => c.id === id);
- return col?.width || '1fr';
- }).join(' '),
- gap: '12px',
- padding: riskPresets.density === 'compact' ? '8px 12px' : riskPresets.density === 'comfortable' ? '12px 18px' : '16px 24px',
- borderBottom: '1px solid var(--border)',
- fontSize: riskPresets.density === 'compact' ? '11px' : riskPresets.density === 'comfortable' ? '12px' : '13px',
- alignItems: 'center',
- }}
- >
- {riskPresets.visibleColumns.includes('label') && (
- {risk.label}
- )}
- {riskPresets.visibleColumns.includes('severity') && (
-
- {risk.severity}
-
- )}
- {riskPresets.visibleColumns.includes('status') && (
-
- {risk.active ? 'Active' : 'Inactive'}
-
- )}
-
- ))}
-
+
Risk Signals
+
+ {risks.map((risk) => (
+
+ ))}
+
+
);
}
diff --git a/src/components/dashboard/CohortRetentionView.tsx b/src/components/dashboard/CohortRetentionView.tsx
new file mode 100644
index 00000000..3fca938b
--- /dev/null
+++ b/src/components/dashboard/CohortRetentionView.tsx
@@ -0,0 +1,689 @@
+import React, { useMemo, useState } from 'react';
+import {
+ BarChart2,
+ Calendar,
+ Download,
+ FileJson,
+ FileSpreadsheet,
+ Filter,
+ Grid,
+ Info,
+ RefreshCw,
+ TrendingUp,
+ Users,
+} from 'lucide-react';
+import {
+ CartesianGrid,
+ Legend,
+ Line,
+ LineChart,
+ ResponsiveContainer,
+ Tooltip,
+ XAxis,
+ YAxis,
+} from 'recharts';
+import {
+ calculateCohortRetention,
+ exportCohortDataAsCsv,
+ exportCohortDataAsJson,
+ generateMockAccountActivities,
+ type AccountActivityRecord,
+ type ActivityFilter,
+ type CohortGranularity,
+ type CohortRetentionResult,
+} from '../../lib/cohortRetention';
+import AccessibleChart from '../charts/AccessibleChart';
+
+export interface CohortRetentionViewProps {
+ /** Optional custom account activity records. If not provided, mock data is used */
+ activities?: AccountActivityRecord[];
+ /** Optional container title override */
+ title?: string;
+ /** Optional callback when data is exported */
+ onExport?: (format: 'csv' | 'json', payload: string) => void;
+}
+
+const cardStyle: React.CSSProperties = {
+ background: 'var(--bg-card, #131722)',
+ border: '1px solid var(--border, #2a2e39)',
+ borderRadius: 'var(--radius-lg, 12px)',
+ padding: '16px',
+ boxShadow: '0 4px 12px rgba(0, 0, 0, 0.15)',
+};
+
+const selectStyle: React.CSSProperties = {
+ background: 'var(--bg-elevated, #1e222d)',
+ border: '1px solid var(--border, #2a2e39)',
+ color: 'var(--text-primary, #f0f3fa)',
+ borderRadius: 'var(--radius-md, 6px)',
+ padding: '6px 10px',
+ fontSize: '12px',
+ outline: 'none',
+ cursor: 'pointer',
+};
+
+const buttonStyle: React.CSSProperties = {
+ background: 'var(--bg-elevated, #1e222d)',
+ border: '1px solid var(--border, #2a2e39)',
+ color: 'var(--text-primary, #f0f3fa)',
+ borderRadius: 'var(--radius-md, 6px)',
+ padding: '6px 12px',
+ fontSize: '12px',
+ display: 'inline-flex',
+ alignItems: 'center',
+ gap: '6px',
+ cursor: 'pointer',
+ transition: 'all 0.15s ease',
+};
+
+function downloadFile(filename: string, content: string, mimeType: string) {
+ try {
+ if (
+ typeof window !== 'undefined' &&
+ typeof URL !== 'undefined' &&
+ typeof URL.createObjectURL === 'function'
+ ) {
+ const blob = new Blob([content], { type: mimeType });
+ const url = URL.createObjectURL(blob);
+ const a = document.createElement('a');
+ a.href = url;
+ a.download = filename;
+ a.click();
+ if (typeof URL.revokeObjectURL === 'function') {
+ URL.revokeObjectURL(url);
+ }
+ return;
+ }
+ } catch (e) {
+ // Fallback or ignore in unsupported test/server environments
+ }
+}
+
+/**
+ * Returns background color and text color for heatmap cells based on retention %
+ */
+function getCellColor(percentage: number): { background: string; color: string; border: string } {
+ if (percentage <= 0) {
+ return {
+ background: 'rgba(255, 255, 255, 0.02)',
+ color: 'var(--text-muted, #787b86)',
+ border: '1px solid rgba(255, 255, 255, 0.04)',
+ };
+ }
+ if (percentage >= 80) {
+ return {
+ background:
+ 'linear-gradient(135deg, rgba(6, 182, 212, 0.45) 0%, rgba(14, 165, 233, 0.45) 100%)',
+ color: '#ffffff',
+ border: '1px solid rgba(6, 182, 212, 0.6)',
+ };
+ }
+ if (percentage >= 60) {
+ return {
+ background:
+ 'linear-gradient(135deg, rgba(16, 185, 129, 0.4) 0%, rgba(5, 150, 105, 0.4) 100%)',
+ color: '#ffffff',
+ border: '1px solid rgba(16, 185, 129, 0.5)',
+ };
+ }
+ if (percentage >= 40) {
+ return {
+ background:
+ 'linear-gradient(135deg, rgba(245, 158, 11, 0.4) 0%, rgba(217, 119, 6, 0.4) 100%)',
+ color: '#ffffff',
+ border: '1px solid rgba(245, 158, 11, 0.5)',
+ };
+ }
+ if (percentage >= 20) {
+ return {
+ background:
+ 'linear-gradient(135deg, rgba(249, 115, 22, 0.35) 0%, rgba(2ea, 88, 12, 0.35) 100%)',
+ color: '#f0f3fa',
+ border: '1px solid rgba(249, 115, 22, 0.4)',
+ };
+ }
+ return {
+ background:
+ 'linear-gradient(135deg, rgba(139, 92, 246, 0.25) 0%, rgba(124, 58, 237, 0.25) 100%)',
+ color: '#d1d5db',
+ border: '1px solid rgba(139, 92, 246, 0.3)',
+ };
+}
+
+export default function CohortRetentionView({
+ activities: externalActivities,
+ title = 'Cohort Retention Views',
+ onExport,
+}: CohortRetentionViewProps) {
+ const [granularity, setGranularity] = useState
('week');
+ const [activityFilter, setActivityFilter] = useState('all');
+ const [viewMode, setViewMode] = useState<'percent' | 'count'>('percent');
+ const [maxPeriods, setMaxPeriods] = useState(8);
+ const [useMockFallback, setUseMockFallback] = useState(false);
+ const [mockSeed, setMockSeed] = useState(1);
+
+ // Generate mock dataset when explicitly toggled or when external dataset is empty
+ const mockActivities = useMemo(() => {
+ return generateMockAccountActivities(60, 90);
+ }, [mockSeed]);
+
+ const activeRecords = useMemo(() => {
+ if (useMockFallback) return mockActivities;
+ if (externalActivities && externalActivities.length > 0) return externalActivities;
+ return mockActivities; // Default to mock activities for demonstration
+ }, [externalActivities, mockActivities, useMockFallback]);
+
+ // Calculate cohort retention
+ const retentionResult: CohortRetentionResult = useMemo(() => {
+ return calculateCohortRetention(activeRecords, {
+ granularity,
+ activityFilter,
+ maxPeriods,
+ maxCohorts: 12,
+ });
+ }, [activeRecords, granularity, activityFilter, maxPeriods]);
+
+ // Handle Export CSV
+ const handleExportCsv = () => {
+ const csv = exportCohortDataAsCsv(retentionResult);
+ if (onExport) onExport('csv', csv);
+ downloadFile(`cohort-retention-${granularity}.csv`, csv, 'text/csv');
+ };
+
+ // Handle Export JSON
+ const handleExportJson = () => {
+ const json = exportCohortDataAsJson(retentionResult);
+ if (onExport) onExport('json', json);
+ downloadFile(`cohort-retention-${granularity}.json`, json, 'application/json');
+ };
+
+ const handleRegenerateMock = () => {
+ setUseMockFallback(true);
+ setMockSeed((prev) => prev + 1);
+ };
+
+ if (!retentionResult.ok) {
+ return (
+
+
+ Error Loading Cohort Retention Data
+
+
+ {retentionResult.error.message}
+
+
+
+ {/* Top Header Card */}
+
+
+
+
+
+
+ {title}
+
+
+
+ Group accounts by initial activity period and analyze cohort retention over time.
+
+
+
+ {/* Actions */}
+
+
+
+
+
+
+
+ {/* Toolbar & Filters */}
+
+
+ {/* Granularity */}
+
+
+ Period:
+
+
+
+ {/* Activity Type */}
+
+
+
+ Activity:
+
+
+
+
+ {/* Max Periods */}
+
+
+ Periods:
+
+
+
+
+
+ {/* View Mode Toggle */}
+
+
+
+
+
+
+
+ {/* Metric Cards Summary */}
+
+
+
+ Total Tracked Cohorts
+
+
+ {stats.totalCohorts}
+
+
+
+
+
+ Unique Tracked Accounts
+
+
+ {stats.totalUniqueAccounts}
+
+
+
+
+
+ Avg Period 1 Retention (+1 {granularity})
+
+
+ {stats.avgPeriod1Retention}%
+
+
+
+
+
+ Avg Period 4 Retention (+4 {granularity}s)
+
+
+ {stats.avgPeriod4Retention}%
+
+
+
+
+
+ Best Performing Cohort
+
+
+ {stats.bestCohortKey || 'N/A'}
+
+
+
+
+ {/* Cohort Heatmap Matrix Table */}
+
+
+
+
+
+ Cohort Retention Matrix
+
+
+
+ Displaying: {viewMode === 'percent' ? 'Retention Rate (%)' : 'Active Accounts (#)'}
+
+
+
+ {cohorts.length === 0 ? (
+
+
+
+ No account activity data matched the selected cohort filters.
+
+
+ ) : (
+
+
+
+
+ |
+ Cohort
+ |
+
+ Accounts
+ |
+ {periodsHeader.map((header, idx) => (
+
+ {header}
+ |
+ ))}
+
+
+
+ {cohorts.map((row) => (
+
+ {/* Cohort Label */}
+ |
+ {row.cohortKey}
+
+ {row.cohortLabel}
+
+ |
+
+ {/* Total Cohort Size */}
+
+ {row.totalAccounts}
+ |
+
+ {/* Period Cells */}
+ {periodsHeader.map((_, pIdx) => {
+ const pct = row.retentionByPeriod[pIdx] ?? 0;
+ const activeCount = row.activeAccountsByPeriod[pIdx] ?? 0;
+ const cellStyle = getCellColor(pct);
+
+ return (
+
+ {viewMode === 'percent' ? `${pct}%` : activeCount}
+ |
+ );
+ })}
+
+ ))}
+
+
+
+ )}
+
+
+ {/* Average Retention Curve Line Chart */}
+
+
+
+
+
+
+ [`${value}%`, 'Avg Retention']}
+ />
+
+
+
+
+
+
{children}
+ ),
+ };
+});
+
+describe('CohortRetentionView Component', () => {
+ const baseMs = Date.UTC(2026, 5, 1);
+ const weekMs = 7 * 24 * 60 * 60 * 1000;
+
+ const mockActivities: AccountActivityRecord[] = [
+ { accountId: 'GA_1', timestamp: baseMs, activityType: 'payment' },
+ { accountId: 'GA_2', timestamp: baseMs, activityType: 'payment' },
+ { accountId: 'GA_1', timestamp: baseMs + weekMs, activityType: 'payment' },
+ { accountId: 'GA_3', timestamp: baseMs + weekMs, activityType: 'payment' },
+ ];
+
+ it('renders cohort retention header, stat cards, table, and controls', () => {
+ render(
+
+ );
+
+ // Header & Title
+ expect(screen.getByText('Account Activity Cohort Retention')).toBeInTheDocument();
+ expect(
+ screen.getByText(
+ 'Group accounts by initial activity period and analyze cohort retention over time.'
+ )
+ ).toBeInTheDocument();
+
+ // Metric Cards
+ expect(screen.getByText('Total Tracked Cohorts')).toBeInTheDocument();
+ expect(screen.getByText('Unique Tracked Accounts')).toBeInTheDocument();
+ expect(screen.getByText('Avg Period 1 Retention (+1 week)')).toBeInTheDocument();
+
+ // Heatmap Matrix Table
+ expect(screen.getByText('Cohort Retention Matrix')).toBeInTheDocument();
+ expect(screen.getByText('Wk 0')).toBeInTheDocument();
+ expect(screen.getByText('+1 Wk')).toBeInTheDocument();
+ });
+
+ it('allows changing granularity and view mode toggles', () => {
+ render();
+
+ // Select Daily Granularity
+ const granularitySelect = screen.getByLabelText('Select Cohort Period Granularity');
+ fireEvent.change(granularitySelect, { target: { value: 'day' } });
+ expect(screen.getByText('Day 0')).toBeInTheDocument();
+
+ // Toggle Account Count mode
+ const countBtn = screen.getByLabelText('Show Account Counts');
+ fireEvent.click(countBtn);
+
+ expect(screen.getByText('Displaying: Active Accounts (#)')).toBeInTheDocument();
+
+ // Toggle Percentage mode back
+ const percentBtn = screen.getByLabelText('Show Retention Percentages');
+ fireEvent.click(percentBtn);
+ expect(screen.getByText('Displaying: Retention Rate (%)')).toBeInTheDocument();
+ });
+
+ it('triggers onExport callback when CSV or JSON buttons are clicked', () => {
+ const handleExport = vi.fn();
+ render();
+
+ const csvBtn = screen.getByLabelText('Export CSV');
+ fireEvent.click(csvBtn);
+ expect(handleExport).toHaveBeenCalledWith(
+ 'csv',
+ expect.stringContaining('# Cohort Retention Report')
+ );
+
+ const jsonBtn = screen.getByLabelText('Export JSON');
+ fireEvent.click(jsonBtn);
+ expect(handleExport).toHaveBeenCalledWith('json', expect.stringContaining('"ok": true'));
+ });
+
+ it('renders demo data when Demo Data button is clicked', () => {
+ render();
+
+ const demoBtn = screen.getByLabelText('Refresh Demo Data');
+ fireEvent.click(demoBtn);
+
+ expect(screen.getByText('Total Tracked Cohorts')).toBeInTheDocument();
+ expect(screen.getByText('Cohort Retention Matrix')).toBeInTheDocument();
+ });
+});
diff --git a/src/lib/__tests__/cohortRetention.test.ts b/src/lib/__tests__/cohortRetention.test.ts
new file mode 100644
index 00000000..37b7c515
--- /dev/null
+++ b/src/lib/__tests__/cohortRetention.test.ts
@@ -0,0 +1,269 @@
+import { describe, expect, it } from 'vitest';
+import {
+ calculateCohortRetention,
+ exportCohortDataAsCsv,
+ exportCohortDataAsJson,
+ formatCohortHeader,
+ generateMockAccountActivities,
+ generatePeriodsHeader,
+ getPeriodDiff,
+ getPeriodStartTimestamp,
+ parseTimestamp,
+ type AccountActivityRecord,
+} from '../cohortRetention';
+
+describe('Cohort Retention Library', () => {
+ // ── 1. Primary Flows ─────────────────────────────────────────────────────────
+
+ describe('Primary Calculation Flow', () => {
+ it('calculates weekly cohort retention correctly', () => {
+ const baseMs = Date.UTC(2026, 5, 1); // Monday, Jun 1, 2026
+ const weekMs = 7 * 24 * 60 * 60 * 1000;
+
+ const records: AccountActivityRecord[] = [
+ // Cohort 1: Account A & B (first seen week 0)
+ { accountId: 'GACCOUNT_A', timestamp: baseMs, activityType: 'payment' },
+ { accountId: 'GACCOUNT_B', timestamp: baseMs + 1000, activityType: 'payment' },
+
+ // Week 1 activity: Account A returns, Account B inactive
+ { accountId: 'GACCOUNT_A', timestamp: baseMs + weekMs, activityType: 'payment' },
+
+ // Week 2 activity: Account A & B both active
+ { accountId: 'GACCOUNT_A', timestamp: baseMs + 2 * weekMs, activityType: 'payment' },
+ { accountId: 'GACCOUNT_B', timestamp: baseMs + 2 * weekMs, activityType: 'payment' },
+
+ // Cohort 2: Account C (first seen week 1)
+ { accountId: 'GACCOUNT_C', timestamp: baseMs + weekMs, activityType: 'payment' },
+ { accountId: 'GACCOUNT_C', timestamp: baseMs + 2 * weekMs, activityType: 'payment' },
+ ];
+
+ const result = calculateCohortRetention(records, {
+ granularity: 'week',
+ maxPeriods: 3,
+ });
+
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ const { cohorts, stats, periodsHeader } = result.data;
+ expect(periodsHeader).toEqual(['Wk 0', '+1 Wk', '+2 Wk']);
+ expect(cohorts.length).toBe(2);
+
+ // Cohort 1 (Jun 1)
+ const cohort1 = cohorts[0];
+ expect(cohort1.totalAccounts).toBe(2);
+ expect(cohort1.retentionByPeriod).toEqual([100, 50, 100]); // Wk 0: 100%, Wk 1: 50% (A only), Wk 2: 100% (A & B)
+ expect(cohort1.activeAccountsByPeriod).toEqual([2, 1, 2]);
+
+ // Cohort 2 (Jun 8)
+ const cohort2 = cohorts[1];
+ expect(cohort2.totalAccounts).toBe(1);
+ expect(cohort2.retentionByPeriod).toEqual([100, 100, 0]); // Wk 0: 100%, Wk 1: 100% (C), Wk 2: 0%
+ expect(cohort2.activeAccountsByPeriod).toEqual([1, 1, 0]);
+
+ // Summary Stats
+ expect(stats.totalCohorts).toBe(2);
+ expect(stats.totalUniqueAccounts).toBe(3);
+ expect(stats.avgPeriod1Retention).toBe(75); // (50 + 100) / 2
+ });
+
+ it('supports daily cohort retention', () => {
+ const dayMs = 24 * 60 * 60 * 1000;
+ const baseMs = Date.UTC(2026, 5, 1);
+
+ const records: AccountActivityRecord[] = [
+ { accountId: 'GA', timestamp: baseMs },
+ { accountId: 'GA', timestamp: baseMs + dayMs },
+ ];
+
+ const result = calculateCohortRetention(records, { granularity: 'day', maxPeriods: 2 });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ expect(result.data.periodsHeader).toEqual(['Day 0', '+1 Day']);
+ expect(result.data.cohorts[0].retentionByPeriod).toEqual([100, 100]);
+ });
+
+ it('supports monthly cohort retention', () => {
+ const baseMs = Date.UTC(2026, 0, 15); // Jan 15, 2026
+ const febMs = Date.UTC(2026, 1, 10); // Feb 10, 2026
+
+ const records: AccountActivityRecord[] = [
+ { accountId: 'GA', timestamp: baseMs },
+ { accountId: 'GA', timestamp: febMs },
+ ];
+
+ const result = calculateCohortRetention(records, { granularity: 'month', maxPeriods: 2 });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ expect(result.data.periodsHeader).toEqual(['Mo 0', '+1 Mo']);
+ expect(result.data.cohorts[0].retentionByPeriod).toEqual([100, 100]);
+ });
+
+ it('filters by activity type correctly', () => {
+ const baseMs = Date.UTC(2026, 5, 1);
+ const records: AccountActivityRecord[] = [
+ { accountId: 'GA', timestamp: baseMs, activityType: 'payment' },
+ { accountId: 'GA', timestamp: baseMs + 86400000, activityType: 'invoke_host_function' },
+ ];
+
+ const paymentResult = calculateCohortRetention(records, {
+ granularity: 'day',
+ activityFilter: 'payment',
+ maxPeriods: 2,
+ });
+
+ expect(paymentResult.ok).toBe(true);
+ if (!paymentResult.ok) return;
+ expect(paymentResult.data.cohorts[0].retentionByPeriod).toEqual([100, 0]);
+ });
+
+ it('exports CSV and JSON formatted output', () => {
+ const records = generateMockAccountActivities(10, 30);
+ const result = calculateCohortRetention(records, { granularity: 'week' });
+
+ const csv = exportCohortDataAsCsv(result);
+ expect(csv).toContain('# Cohort Retention Report (WEEK)');
+ expect(csv).toContain('Cohort Size (Accounts)');
+
+ const json = exportCohortDataAsJson(result);
+ const parsed = JSON.parse(json);
+ expect(parsed.ok).toBe(true);
+ expect(parsed.data.cohorts.length).toBeGreaterThan(0);
+ });
+ });
+
+ // ── 2. Boundary Cases ───────────────────────────────────────────────────────
+
+ describe('Boundary Cases', () => {
+ it('handles empty records array gracefully', () => {
+ const result = calculateCohortRetention([]);
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ expect(result.data.cohorts).toEqual([]);
+ expect(result.data.stats.totalCohorts).toBe(0);
+ expect(result.data.stats.totalUniqueAccounts).toBe(0);
+ });
+
+ it('handles single account with single activity', () => {
+ const result = calculateCohortRetention([
+ { accountId: 'GA', timestamp: '2026-06-01T10:00:00Z' },
+ ]);
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ expect(result.data.cohorts.length).toBe(1);
+ expect(result.data.cohorts[0].totalAccounts).toBe(1);
+ expect(result.data.cohorts[0].retentionByPeriod[0]).toBe(100);
+ });
+
+ it('handles 0% retention in all subsequent periods', () => {
+ const baseMs = Date.UTC(2026, 5, 1);
+ const records: AccountActivityRecord[] = [
+ { accountId: 'GA', timestamp: baseMs },
+ { accountId: 'GB', timestamp: baseMs },
+ ];
+
+ const result = calculateCohortRetention(records, { granularity: 'week', maxPeriods: 4 });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ expect(result.data.cohorts[0].retentionByPeriod).toEqual([100, 0, 0, 0]);
+ });
+
+ it('filters cohorts by minCohortSize', () => {
+ const baseMs = Date.UTC(2026, 5, 1);
+ const records: AccountActivityRecord[] = [
+ { accountId: 'GA', timestamp: baseMs },
+ { accountId: 'GB', timestamp: baseMs },
+ { accountId: 'GC', timestamp: baseMs + 7 * 86400000 },
+ ];
+
+ const result = calculateCohortRetention(records, { granularity: 'week', minCohortSize: 2 });
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ // Only the first cohort has >= 2 accounts
+ expect(result.data.cohorts.length).toBe(1);
+ expect(result.data.cohorts[0].totalAccounts).toBe(2);
+ });
+
+ it('parses timestamps in string, number, and Date formats', () => {
+ expect(parseTimestamp('2026-06-01T00:00:00Z')).toBe(1780272000000);
+ expect(parseTimestamp(1780272000000)).toBe(1780272000000);
+ expect(parseTimestamp(new Date(1780272000000))).toBe(1780272000000);
+ expect(Number.isNaN(parseTimestamp('invalid-date'))).toBe(true);
+ expect(Number.isNaN(parseTimestamp(null))).toBe(true);
+ });
+
+ it('calculates period differences correctly across month boundaries', () => {
+ const jan15 = Date.UTC(2026, 0, 15);
+ const feb15 = Date.UTC(2026, 1, 15);
+ const mar01 = Date.UTC(2026, 2, 1);
+
+ expect(getPeriodDiff(jan15, feb15, 'month')).toBe(1);
+ expect(getPeriodDiff(jan15, mar01, 'month')).toBe(2);
+ });
+ });
+
+ // ── 3. Failure Paths ────────────────────────────────────────────────────────
+
+ describe('Failure Paths & Invalid Input', () => {
+ it('returns error when input is null or non-array', () => {
+ const resultNull = calculateCohortRetention(null as any);
+ expect(resultNull.ok).toBe(false);
+ if (!resultNull.ok) {
+ expect(resultNull.error.code).toBe('INVALID_INPUT');
+ }
+
+ const resultNotArray = calculateCohortRetention({} as any);
+ expect(resultNotArray.ok).toBe(false);
+ if (!resultNotArray.ok) {
+ expect(resultNotArray.error.code).toBe('INVALID_INPUT');
+ }
+ });
+
+ it('returns error for invalid granularity option', () => {
+ const result = calculateCohortRetention([], { granularity: 'year' as any });
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.code).toBe('INVALID_INPUT');
+ expect(result.error.message).toContain('Invalid granularity');
+ }
+ });
+
+ it('returns error for negative maxPeriods or maxCohorts', () => {
+ const result = calculateCohortRetention([], { maxPeriods: -5 });
+ expect(result.ok).toBe(false);
+ if (!result.ok) {
+ expect(result.error.code).toBe('INVALID_INPUT');
+ }
+ });
+
+ it('ignores malformed records missing accountId or valid timestamp without crashing', () => {
+ const records: any[] = [
+ { accountId: '', timestamp: '2026-06-01' },
+ { accountId: 'GA', timestamp: 'invalid-date' },
+ { accountId: null, timestamp: 12345 },
+ { accountId: 'GVALID', timestamp: '2026-06-01T00:00:00Z' },
+ ];
+
+ const result = calculateCohortRetention(records);
+ expect(result.ok).toBe(true);
+ if (!result.ok) return;
+
+ expect(result.data.cohorts.length).toBe(1);
+ expect(result.data.cohorts[0].totalAccounts).toBe(1);
+ });
+
+ it('handles CSV export error state gracefully', () => {
+ const csv = exportCohortDataAsCsv({
+ ok: false,
+ error: { code: 'CALCULATION_FAILED', message: 'Test failure' },
+ });
+ expect(csv).toContain('Error,CALCULATION_FAILED,Test failure');
+ });
+ });
+});
diff --git a/src/lib/__tests__/costThresholdManager.test.ts b/src/lib/__tests__/costThresholdManager.test.ts
new file mode 100644
index 00000000..46bfe468
--- /dev/null
+++ b/src/lib/__tests__/costThresholdManager.test.ts
@@ -0,0 +1,285 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import { CostThresholdManager, type CostTagRule, type TransactionInput } from '../costThresholdManager'
+
+describe('CostThresholdManager', () => {
+ let manager: CostThresholdManager
+
+ beforeEach(() => {
+ // Clear mock storage if any
+ if (typeof window !== 'undefined' && window.localStorage) {
+ window.localStorage.clear()
+ }
+ manager = new CostThresholdManager([], 'test_cost_threshold_rules')
+ })
+
+ // ---------------------------------------------------------------------------
+ // Primary Flow
+ // ---------------------------------------------------------------------------
+ describe('Primary Flow', () => {
+ it('should add, update, and retrieve cost tag rules', () => {
+ const rule = manager.addRule({
+ tag: 'billing',
+ memoPrefix: '[APP:billing]',
+ budgetLimitStroops: 10_000_000, // 1 XLM
+ warningThresholdPercent: 80,
+ })
+
+ expect(rule.id).toBeDefined()
+ expect(rule.tag).toBe('billing')
+ expect(rule.enabled).toBe(true)
+
+ const updated = manager.updateRule(rule.id, { budgetLimitStroops: 20_000_000 })
+ expect(updated?.budgetLimitStroops).toBe(20_000_000)
+
+ const rules = manager.getRules()
+ expect(rules).toHaveLength(1)
+ expect(rules[0].budgetLimitStroops).toBe(20_000_000)
+ })
+
+ it('should attribute fees and volume to configured application tags by memo prefix', () => {
+ manager.addRule({
+ tag: 'billing',
+ memoPrefix: '[APP:billing]',
+ budgetLimitStroops: 10_000_000, // 1 XLM
+ })
+ manager.addRule({
+ tag: 'auth',
+ memoPrefix: 'AUTH:',
+ budgetLimitStroops: 5_000_000,
+ })
+
+ const transactions: TransactionInput[] = [
+ {
+ id: 'tx_1',
+ fee_charged: '100',
+ memo: '[APP:billing] Invoice #101',
+ created_at: '2026-09-28T10:00:00Z',
+ operations: [{ amount: '50000000' }], // 5 XLM volume
+ },
+ {
+ id: 'tx_2',
+ fee_charged: '200',
+ memo: '[APP:billing] Invoice #102',
+ created_at: '2026-09-28T10:05:00Z',
+ operations: [{ amount: '20000000' }], // 2 XLM volume
+ },
+ {
+ id: 'tx_3',
+ fee_charged: '150',
+ memo: 'AUTH: Session renewal',
+ created_at: '2026-09-28T10:10:00Z',
+ },
+ ]
+
+ const summary = manager.attributeTransactions(transactions)
+
+ expect(summary.totalTransactions).toBe(3)
+ expect(summary.totalAttributedFeeStroops).toBe(450)
+ expect(summary.totalAttributedFeeXlm).toBe(450 / 10_000_000)
+ expect(summary.totalUnattributedFeeStroops).toBe(0)
+ expect(summary.tagBreakdown).toHaveLength(2)
+
+ const billingTag = summary.tagBreakdown.find((b) => b.tag === 'billing')
+ expect(billingTag).toBeDefined()
+ expect(billingTag?.transactionCount).toBe(2)
+ expect(billingTag?.totalFeeStroops).toBe(300)
+ expect(billingTag?.averageFeeStroops).toBe(150)
+ expect(billingTag?.totalVolumeStroops).toBe(70_000_000)
+ expect(billingTag?.totalVolumeXlm).toBe(7)
+ expect(billingTag?.status).toBe('ok')
+ })
+
+ it('should auto-discover tag prefixes when no explicit rule matches', () => {
+ const transactions: TransactionInput[] = [
+ {
+ id: 'tx_auto_1',
+ fee_charged: '500',
+ memo: '[APP:nft-drop] Mint #42',
+ },
+ {
+ id: 'tx_auto_2',
+ fee_charged: '300',
+ memo: 'TAG:rewards User payout',
+ },
+ ]
+
+ const summary = manager.attributeTransactions(transactions)
+
+ expect(summary.totalAttributedFeeStroops).toBe(800)
+ expect(summary.tagBreakdown).toHaveLength(2)
+
+ const nftTag = summary.tagBreakdown.find((b) => b.tag === 'nft-drop')
+ expect(nftTag).toBeDefined()
+ expect(nftTag?.ruleId).toBe('auto-discovered')
+ expect(nftTag?.status).toBe('unbudgeted')
+ })
+
+ it('should export attribution report in JSON and CSV formats', () => {
+ manager.addRule({
+ tag: 'payments',
+ memoPrefix: 'PAY:',
+ budgetLimitStroops: 10_000_000,
+ })
+
+ const transactions: TransactionInput[] = [
+ { id: 'tx_1', fee_charged: '1000', memo: 'PAY: Vendor invoice' },
+ ]
+
+ const summary = manager.attributeTransactions(transactions)
+
+ const jsonExport = manager.exportAttributionReport(summary, 'json')
+ expect(jsonExport).toContain('"tag": "payments"')
+ expect(jsonExport).toContain('"totalFeeStroops": 1000')
+
+ const csvExport = manager.exportAttributionReport(summary, 'csv')
+ expect(csvExport).toContain('Tag,Rule ID,Transactions')
+ expect(csvExport).toContain('"payments"')
+ expect(csvExport).toContain('1000')
+ }
+
+)
+ })
+
+ // ---------------------------------------------------------------------------
+ // Boundary Cases
+ // ---------------------------------------------------------------------------
+ describe('Boundary Cases', () => {
+ it('should handle empty transaction list gracefully', () => {
+ const summary = manager.attributeTransactions([])
+
+ expect(summary.totalTransactions).toBe(0)
+ expect(summary.totalOperations).toBe(0)
+ expect(summary.totalAttributedFeeStroops).toBe(0)
+ expect(summary.tagBreakdown).toHaveLength(0)
+ expect(summary.thresholdAlerts).toHaveLength(0)
+ })
+
+ it('should trigger warning alert on reaching exact warning threshold percentage', () => {
+ manager.addRule({
+ tag: 'swap',
+ memoPrefix: 'SWAP:',
+ budgetLimitStroops: 1000,
+ warningThresholdPercent: 80,
+ })
+
+ const transactions: TransactionInput[] = [
+ { id: 'tx_1', fee_charged: '800', memo: 'SWAP: XLM-USDC' }, // Exactly 80% (800 / 1000)
+ ]
+
+ const summary = manager.attributeTransactions(transactions)
+ const swapRecord = summary.tagBreakdown.find((b) => b.tag === 'swap')
+
+ expect(swapRecord?.budgetUsedPercent).toBe(80)
+ expect(swapRecord?.status).toBe('warning')
+ expect(summary.thresholdAlerts).toHaveLength(1)
+ expect(summary.thresholdAlerts[0].severity).toBe('warning')
+ expect(summary.thresholdAlerts[0].tag).toBe('swap')
+ })
+
+ it('should trigger exceeded alert on reaching or exceeding 100% budget', () => {
+ manager.addRule({
+ tag: 'governance',
+ memoPrefix: 'GOV:',
+ budgetLimitStroops: 1000,
+ })
+
+ const transactions: TransactionInput[] = [
+ { id: 'tx_1', fee_charged: '1000', memo: 'GOV: Vote #1' }, // Exactly 100%
+ ]
+
+ const summary = manager.attributeTransactions(transactions)
+ const govRecord = summary.tagBreakdown.find((b) => b.tag === 'governance')
+
+ expect(govRecord?.budgetUsedPercent).toBe(100)
+ expect(govRecord?.status).toBe('exceeded')
+ expect(summary.thresholdAlerts).toHaveLength(1)
+ expect(summary.thresholdAlerts[0].severity).toBe('exceeded')
+ })
+
+ it('should handle zero-fee transactions correctly', () => {
+ manager.addRule({ tag: 'free-tier', memoPrefix: 'FREE:' })
+
+ const transactions: TransactionInput[] = [
+ { id: 'tx_zero', fee_charged: '0', memo: 'FREE: Zero fee operation' },
+ ]
+
+ const summary = manager.attributeTransactions(transactions)
+ const record = summary.tagBreakdown.find((b) => b.tag === 'free-tier')
+
+ expect(record?.totalFeeStroops).toBe(0)
+ expect(record?.averageFeeStroops).toBe(0)
+ })
+ })
+
+ // ---------------------------------------------------------------------------
+ // Failure Cases & Robustness
+ // ---------------------------------------------------------------------------
+ describe('Failure Cases & Error Handling', () => {
+ it('should handle null or undefined input gracefully', () => {
+ // @ts-expect-error - testing invalid runtime input
+ const summaryNull = manager.attributeTransactions(null)
+ expect(summaryNull.totalTransactions).toBe(0)
+ expect(summaryNull.warnings).toContain('Input transactions was empty or not an array.')
+
+ // @ts-expect-error - testing invalid runtime input
+ const summaryUndefined = manager.attributeTransactions(undefined)
+ expect(summaryUndefined.totalTransactions).toBe(0)
+ })
+
+ it('should handle malformed transaction records with NaN or negative fees', () => {
+ manager.addRule({ tag: 'test-app', memoPrefix: 'TEST:' })
+
+ const transactions: TransactionInput[] = [
+ { id: 'tx_bad_1', fee_charged: 'invalid_number', memo: 'TEST: 1' },
+ { id: 'tx_bad_2', fee_charged: '-500', memo: 'TEST: 2' },
+ { id: 'tx_good', fee_charged: '200', memo: 'TEST: 3' },
+ ]
+
+ const summary = manager.attributeTransactions(transactions)
+ const record = summary.tagBreakdown.find((b) => b.tag === 'test-app')
+
+ // Non-numeric and negative fees are safely parsed as 0
+ expect(record?.totalFeeStroops).toBe(200)
+ expect(record?.transactionCount).toBe(3)
+ })
+
+ it('should handle invalid regex patterns in rules without throwing', () => {
+ manager.addRule({
+ tag: 'broken-regex',
+ memoPattern: '[invalid regex (unclosed bracket',
+ enabled: true,
+ })
+
+ const transactions: TransactionInput[] = [
+ { id: 'tx_1', fee_charged: '100', memo: 'Some random memo' },
+ ]
+
+ expect(() => manager.attributeTransactions(transactions)).not.toThrow()
+ })
+
+ it('should handle environments where localStorage throws permission/quota errors (SSR / Private Browsing)', () => {
+ const getItemSpy = vi.spyOn(Storage.prototype, 'getItem').mockImplementation(() => {
+ throw new Error('SecurityError: The operation is insecure.')
+ })
+ const setItemSpy = vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+ throw new Error('QuotaExceededError')
+ })
+
+ expect(() => {
+ const ssrManager = new CostThresholdManager([], 'ssr_test_key')
+ ssrManager.addRule({ tag: 'ssr-tag', memoPrefix: 'SSR:' })
+ ssrManager.attributeTransactions([{ fee_charged: '100', memo: 'SSR: Test' }])
+ }).not.toThrow()
+
+ getItemSpy.mockRestore()
+ setItemSpy.mockRestore()
+ })
+
+ it('should throw error when adding rule without required tag property', () => {
+ expect(() => {
+ // @ts-expect-error - testing missing tag property
+ manager.addRule({})
+ }).toThrow('Invalid rule input: tag is required')
+ })
+ })
+})
diff --git a/src/lib/analytics.ts b/src/lib/analytics.ts
index 31f254cd..d66010a8 100644
--- a/src/lib/analytics.ts
+++ b/src/lib/analytics.ts
@@ -318,12 +318,20 @@ export function buildAnalyticsSnapshot({
networkStats: { latestLedger?: Partial | null; feeStats?: { last_ledger_base_fee?: string; p90_accepted_fee?: string } | null } | null
recentLedgers: Horizon.ServerApi.LedgerRecord[]
}) {
+ const manager = getCostThresholdManager()
+ const costAttribution = manager.attributeTransactions(transactions)
+
return {
account: summarizeBalances(accountData),
transactions: summarizeTransactions(transactions, operations),
network: summarizeNetwork(networkStats, recentLedgers),
activity: buildActivityTimeseries(transactions),
risks: calculateRiskSignals(accountData, transactions),
+ costAttribution,
generatedAt: new Date().toISOString(),
}
}
+
+export { CostThresholdManager, getCostThresholdManager } from './costThresholdManager'
+export type { CostTagRule, CostAttributionRecord, CostAttributionSummary, CostThresholdAlert } from './costThresholdManager'
+
diff --git a/src/lib/cohortRetention.ts b/src/lib/cohortRetention.ts
new file mode 100644
index 00000000..dd69a704
--- /dev/null
+++ b/src/lib/cohortRetention.ts
@@ -0,0 +1,694 @@
+/**
+ * Cohort Retention Library
+ *
+ * Provides cohort analysis for Stellar account activity.
+ * Groups accounts by their first-seen period (Day, Week, or Month)
+ * and calculates retention rates across subsequent activity periods.
+ */
+
+export type CohortGranularity = 'day' | 'week' | 'month';
+
+export type ActivityFilter = 'all' | 'payment' | 'contract' | 'trade';
+
+export interface AccountActivityRecord {
+ /** Account ID or Public Key (e.g. "GABC...") */
+ accountId: string;
+ /** ISO timestamp string or epoch milliseconds or Date object */
+ timestamp: string | number | Date;
+ /** Optional activity or operation type (e.g. "payment", "invoke_host_function", "trade") */
+ activityType?: string;
+ /** Optional transaction amount */
+ amount?: number;
+ /** Optional transaction hash */
+ txHash?: string;
+}
+
+export interface CohortRetentionOptions {
+ /** Time period grouping: 'day', 'week', or 'month'. Default: 'week' */
+ granularity?: CohortGranularity;
+ /** Optional filter by activity type. Default: 'all' */
+ activityFilter?: ActivityFilter;
+ /** Maximum number of cohorts to evaluate. Default: 12 */
+ maxCohorts?: number;
+ /** Maximum number of subsequent periods to display (Period 0 to N). Default: 8 */
+ maxPeriods?: number;
+ /** Minimum cohort size required to include in analysis. Default: 1 */
+ minCohortSize?: number;
+}
+
+export interface CohortRow {
+ /** Unique identifier for the cohort (e.g., "2026-W01" or "2026-06-15") */
+ cohortKey: string;
+ /** Human-readable title for the cohort (e.g., "Jun 15 - Jun 21, 2026") */
+ cohortLabel: string;
+ /** Start ISO timestamp for the cohort period */
+ cohortStartDate: string;
+ /** Total unique accounts first seen in this cohort (Period 0) */
+ totalAccounts: number;
+ /** Retention percentage (0 to 100) for Period 0, 1, 2, ... */
+ retentionByPeriod: number[];
+ /** Count of unique active accounts for Period 0, 1, 2, ... */
+ activeAccountsByPeriod: number[];
+}
+
+export interface CohortCurvePoint {
+ period: number;
+ periodLabel: string;
+ avgRetentionRate: number;
+ totalActiveAccounts: number;
+ evaluatedCohorts: number;
+}
+
+export interface CohortSummaryStats {
+ /** Total cohorts evaluated */
+ totalCohorts: number;
+ /** Total unique accounts across all cohorts */
+ totalUniqueAccounts: number;
+ /** Average retention rate (%) in Period 1 (+1 day/week/month) */
+ avgPeriod1Retention: number;
+ /** Average retention rate (%) in Period 4 (+4 days/weeks/months) */
+ avgPeriod4Retention: number;
+ /** Overall average retention rate across all periods > 0 */
+ overallAvgRetention: number;
+ /** Cohort key with the highest Period 1 retention */
+ bestCohortKey: string | null;
+ /** Average retention curve aggregated across all cohorts */
+ retentionCurve: CohortCurvePoint[];
+}
+
+export interface CohortDataSnapshot {
+ granularity: CohortGranularity;
+ activityFilter: ActivityFilter;
+ cohorts: CohortRow[];
+ periodsHeader: string[];
+ stats: CohortSummaryStats;
+ generatedAt: string;
+}
+
+export type CohortErrorCode =
+ 'INVALID_INPUT' | 'UNSUPPORTED_ENVIRONMENT' | 'CALCULATION_FAILED' | 'NO_DATA';
+
+export interface CohortError {
+ code: CohortErrorCode;
+ message: string;
+ details?: string;
+}
+
+export type CohortRetentionResult =
+ { ok: true; data: CohortDataSnapshot } | { ok: false; error: CohortError };
+
+// ─── Environment & Validation Helpers ─────────────────────────────────────────
+
+/**
+ * Safely parses any valid timestamp format into epoch milliseconds.
+ * Returns NaN if invalid.
+ */
+export function parseTimestamp(ts: string | number | Date | undefined | null): number {
+ if (ts === undefined || ts === null) return NaN;
+ if (ts instanceof Date) return ts.getTime();
+ if (typeof ts === 'number') {
+ if (!Number.isFinite(ts) || ts <= 0) return NaN;
+ return ts;
+ }
+ if (typeof ts === 'string') {
+ const trimmed = ts.trim();
+ if (!trimmed) return NaN;
+ // Check if numeric string
+ if (/^\d+$/.test(trimmed)) {
+ const num = Number(trimmed);
+ return Number.isFinite(num) ? num : NaN;
+ }
+ const parsed = Date.parse(trimmed);
+ return Number.isFinite(parsed) ? parsed : NaN;
+ }
+ return NaN;
+}
+
+/**
+ * Normalizes a date to the start of its cohort period (day, week, or month).
+ * Week starts on Monday.
+ */
+export function getPeriodStartTimestamp(timeMs: number, granularity: CohortGranularity): number {
+ const d = new Date(timeMs);
+ if (isNaN(d.getTime())) return NaN;
+
+ const year = d.getUTCFullYear();
+ const month = d.getUTCMonth();
+ const date = d.getUTCDate();
+
+ if (granularity === 'day') {
+ return Date.UTC(year, month, date);
+ }
+
+ if (granularity === 'week') {
+ // 0 is Sunday, 1 is Monday, ..., 6 is Saturday
+ const dayOfWeek = d.getUTCDay();
+ // Calculate distance to previous Monday (ISO week)
+ const diffToMonday = (dayOfWeek + 6) % 7;
+ return Date.UTC(year, month, date - diffToMonday);
+ }
+
+ if (granularity === 'month') {
+ return Date.UTC(year, month, 1);
+ }
+
+ return NaN;
+}
+
+/**
+ * Computes period offset between two cohort timestamps based on granularity.
+ */
+export function getPeriodDiff(
+ startMs: number,
+ currentMs: number,
+ granularity: CohortGranularity
+): number {
+ if (currentMs < startMs) return -1;
+ const msDiff = currentMs - startMs;
+
+ const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+ if (granularity === 'day') {
+ return Math.floor(msDiff / MS_PER_DAY);
+ }
+
+ if (granularity === 'week') {
+ return Math.floor(msDiff / (7 * MS_PER_DAY));
+ }
+
+ if (granularity === 'month') {
+ const dStart = new Date(startMs);
+ const dCurr = new Date(currentMs);
+ const months =
+ (dCurr.getUTCFullYear() - dStart.getUTCFullYear()) * 12 +
+ (dCurr.getUTCMonth() - dStart.getUTCMonth());
+ return months;
+ }
+
+ return -1;
+}
+
+/**
+ * Formats a period start timestamp into a human-readable cohort key and label.
+ */
+export function formatCohortHeader(
+ startMs: number,
+ granularity: CohortGranularity
+): { key: string; label: string } {
+ const d = new Date(startMs);
+ const isoDate = d.toISOString().slice(0, 10);
+
+ if (granularity === 'day') {
+ return {
+ key: isoDate,
+ label: d.toLocaleDateString('en-US', {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric',
+ timeZone: 'UTC',
+ }),
+ };
+ }
+
+ if (granularity === 'week') {
+ const endOfWeek = new Date(startMs + 6 * 24 * 60 * 60 * 1000);
+ const startStr = d.toLocaleDateString('en-US', {
+ month: 'short',
+ day: 'numeric',
+ timeZone: 'UTC',
+ });
+ const endStr = endOfWeek.toLocaleDateString('en-US', {
+ month: 'short',
+ day: 'numeric',
+ year: 'numeric',
+ timeZone: 'UTC',
+ });
+ return {
+ key: `W-${isoDate}`,
+ label: `${startStr} – ${endStr}`,
+ };
+ }
+
+ // Month
+ const monthStr = d.toLocaleDateString('en-US', {
+ month: 'short',
+ year: 'numeric',
+ timeZone: 'UTC',
+ });
+ const key = isoDate.slice(0, 7); // YYYY-MM
+ return {
+ key: `M-${key}`,
+ label: monthStr,
+ };
+}
+
+/**
+ * Generates header labels for periods (+0, +1, +2, ...).
+ */
+export function generatePeriodsHeader(
+ maxPeriods: number,
+ granularity: CohortGranularity
+): string[] {
+ const unit = granularity === 'day' ? 'Day' : granularity === 'week' ? 'Wk' : 'Mo';
+ const headers: string[] = [`${unit} 0`];
+ for (let i = 1; i < maxPeriods; i++) {
+ headers.push(`+${i} ${unit}`);
+ }
+ return headers;
+}
+
+// ─── Core Calculation Logic ───────────────────────────────────────────────────
+
+/**
+ * Calculates cohort retention rates for account activity data.
+ */
+export function calculateCohortRetention(
+ records: AccountActivityRecord[] | null | undefined,
+ options: CohortRetentionOptions = {}
+): CohortRetentionResult {
+ try {
+ // 1. Validate environment
+ if (typeof Date === 'undefined' || typeof Math === 'undefined') {
+ return {
+ ok: false,
+ error: {
+ code: 'UNSUPPORTED_ENVIRONMENT',
+ message:
+ 'The current runtime environment lacks required JavaScript Date or Math built-ins.',
+ },
+ };
+ }
+
+ // 2. Validate input
+ if (!records || !Array.isArray(records)) {
+ return {
+ ok: false,
+ error: {
+ code: 'INVALID_INPUT',
+ message: 'Input records must be a valid array of account activity entries.',
+ },
+ };
+ }
+
+ const {
+ granularity = 'week',
+ activityFilter = 'all',
+ maxCohorts = 12,
+ maxPeriods = 8,
+ minCohortSize = 1,
+ } = options;
+
+ if (!['day', 'week', 'month'].includes(granularity)) {
+ return {
+ ok: false,
+ error: {
+ code: 'INVALID_INPUT',
+ message: `Invalid granularity "${granularity}". Must be one of: "day", "week", "month".`,
+ },
+ };
+ }
+
+ if (maxCohorts <= 0 || maxPeriods <= 0 || minCohortSize < 0) {
+ return {
+ ok: false,
+ error: {
+ code: 'INVALID_INPUT',
+ message: 'Parameters maxCohorts, maxPeriods, and minCohortSize must be positive numbers.',
+ },
+ };
+ }
+
+ // 3. Filter records by activity type if specified
+ const filteredRecords = records.filter((rec) => {
+ if (!rec || typeof rec.accountId !== 'string' || !rec.accountId.trim()) return false;
+ const tsMs = parseTimestamp(rec.timestamp);
+ if (isNaN(tsMs)) return false;
+
+ if (activityFilter === 'all') return true;
+ if (!rec.activityType) return true;
+
+ const actLower = rec.activityType.toLowerCase();
+ if (activityFilter === 'payment') {
+ return (
+ actLower.includes('payment') || actLower.includes('send') || actLower.includes('receive')
+ );
+ }
+ if (activityFilter === 'contract') {
+ return (
+ actLower.includes('contract') ||
+ actLower.includes('host') ||
+ actLower.includes('invoke') ||
+ actLower.includes('wasm')
+ );
+ }
+ if (activityFilter === 'trade') {
+ return (
+ actLower.includes('trade') ||
+ actLower.includes('offer') ||
+ actLower.includes('swap') ||
+ actLower.includes('dex')
+ );
+ }
+ return true;
+ });
+
+ if (filteredRecords.length === 0) {
+ return {
+ ok: true,
+ data: {
+ granularity,
+ activityFilter,
+ cohorts: [],
+ periodsHeader: generatePeriodsHeader(maxPeriods, granularity),
+ stats: {
+ totalCohorts: 0,
+ totalUniqueAccounts: 0,
+ avgPeriod1Retention: 0,
+ avgPeriod4Retention: 0,
+ overallAvgRetention: 0,
+ bestCohortKey: null,
+ retentionCurve: [],
+ },
+ generatedAt: new Date().toISOString(),
+ },
+ };
+ }
+
+ // 4. Determine first-seen period for each account
+ const accountFirstSeenMap = new Map(); // accountId -> firstPeriodStartMs
+ const accountActivityMap = new Map>>(); // periodStartMs -> Map>
+
+ // Pre-calculate parsed timestamps & period starts
+ const validActivities: { accountId: string; tsMs: number; periodStartMs: number }[] = [];
+ for (const rec of filteredRecords) {
+ const tsMs = parseTimestamp(rec.timestamp);
+ const periodStartMs = getPeriodStartTimestamp(tsMs, granularity);
+ if (isNaN(periodStartMs)) continue;
+ validActivities.push({ accountId: rec.accountId.trim(), tsMs, periodStartMs });
+
+ const prevFirst = accountFirstSeenMap.get(rec.accountId.trim());
+ if (prevFirst === undefined || periodStartMs < prevFirst) {
+ accountFirstSeenMap.set(rec.accountId.trim(), periodStartMs);
+ }
+ }
+
+ if (accountFirstSeenMap.size === 0) {
+ return {
+ ok: true,
+ data: {
+ granularity,
+ activityFilter,
+ cohorts: [],
+ periodsHeader: generatePeriodsHeader(maxPeriods, granularity),
+ stats: {
+ totalCohorts: 0,
+ totalUniqueAccounts: 0,
+ avgPeriod1Retention: 0,
+ avgPeriod4Retention: 0,
+ overallAvgRetention: 0,
+ bestCohortKey: null,
+ retentionCurve: [],
+ },
+ generatedAt: new Date().toISOString(),
+ },
+ };
+ }
+
+ // Group accounts into cohorts by their first-seen period
+ const cohortAccountSetMap = new Map>(); // cohortStartMs -> Set
+ accountFirstSeenMap.forEach((firstSeenMs, accountId) => {
+ let set = cohortAccountSetMap.get(firstSeenMs);
+ if (!set) {
+ set = new Set();
+ cohortAccountSetMap.set(firstSeenMs, set);
+ }
+ set.add(accountId);
+ });
+
+ // 5. Build activity index for each cohort
+ // cohortStartMs -> Map>
+ const cohortActivityIndex = new Map>>();
+
+ // Initialize indexes
+ cohortAccountSetMap.forEach((accounts, cohortStartMs) => {
+ const periodMap = new Map>();
+ for (let p = 0; p < maxPeriods; p++) {
+ periodMap.set(p, new Set());
+ }
+ cohortActivityIndex.set(cohortStartMs, periodMap);
+ });
+
+ // Populate activity for each account's subsequent events
+ for (const act of validActivities) {
+ const cohortStartMs = accountFirstSeenMap.get(act.accountId);
+ if (cohortStartMs === undefined) continue;
+
+ const pDiff = getPeriodDiff(cohortStartMs, act.tsMs, granularity);
+ if (pDiff >= 0 && pDiff < maxPeriods) {
+ const periodMap = cohortActivityIndex.get(cohortStartMs);
+ if (periodMap) {
+ const activeSet = periodMap.get(pDiff);
+ if (activeSet) {
+ activeSet.add(act.accountId);
+ }
+ }
+ }
+ }
+
+ // Sort cohort timestamps chronologically (descending to show latest first, or ascending for chronological)
+ // We sort ascending for cohort timeline order
+ const sortedCohortStarts = Array.from(cohortAccountSetMap.keys()).sort((a, b) => a - b);
+
+ // Limit to maxCohorts (take the most recent maxCohorts)
+ const activeCohortStarts = sortedCohortStarts.slice(-maxCohorts);
+
+ const cohortRows: CohortRow[] = [];
+ let bestCohortKey: string | null = null;
+ let highestP1Retention = -1;
+
+ for (const cohortStartMs of activeCohortStarts) {
+ const accountsInCohort = cohortAccountSetMap.get(cohortStartMs);
+ const totalCohortSize = accountsInCohort ? accountsInCohort.size : 0;
+
+ if (totalCohortSize < minCohortSize) continue;
+
+ const { key, label } = formatCohortHeader(cohortStartMs, granularity);
+ const periodMap = cohortActivityIndex.get(cohortStartMs);
+
+ const activeAccountsByPeriod: number[] = [];
+ const retentionByPeriod: number[] = [];
+
+ for (let p = 0; p < maxPeriods; p++) {
+ const activeSet = periodMap?.get(p);
+ const activeCount = activeSet ? activeSet.size : p === 0 ? totalCohortSize : 0;
+ activeAccountsByPeriod.push(activeCount);
+
+ const rate = totalCohortSize > 0 ? (activeCount / totalCohortSize) * 100 : 0;
+ // Round to 1 decimal place
+ retentionByPeriod.push(Math.round(rate * 10) / 10);
+ }
+
+ if (retentionByPeriod.length > 1 && retentionByPeriod[1] > highestP1Retention) {
+ highestP1Retention = retentionByPeriod[1];
+ bestCohortKey = key;
+ }
+
+ cohortRows.push({
+ cohortKey: key,
+ cohortLabel: label,
+ cohortStartDate: new Date(cohortStartMs).toISOString(),
+ totalAccounts: totalCohortSize,
+ retentionByPeriod,
+ activeAccountsByPeriod,
+ });
+ }
+
+ // 6. Aggregate summary statistics & retention curve
+ const retentionCurve: CohortCurvePoint[] = [];
+ const periodsHeader = generatePeriodsHeader(maxPeriods, granularity);
+
+ let sumP1 = 0;
+ let countP1 = 0;
+ let sumP4 = 0;
+ let countP4 = 0;
+ let sumOverall = 0;
+ let countOverall = 0;
+
+ for (let p = 0; p < maxPeriods; p++) {
+ let periodSumRate = 0;
+ let periodTotalActive = 0;
+ let evaluatedCohortsForP = 0;
+
+ for (const row of cohortRows) {
+ if (p < row.retentionByPeriod.length) {
+ const rate = row.retentionByPeriod[p];
+ periodSumRate += rate;
+ periodTotalActive += row.activeAccountsByPeriod[p] || 0;
+ evaluatedCohortsForP++;
+
+ if (p === 1) {
+ sumP1 += rate;
+ countP1++;
+ }
+ if (p === 4) {
+ sumP4 += rate;
+ countP4++;
+ }
+ if (p > 0) {
+ sumOverall += rate;
+ countOverall++;
+ }
+ }
+ }
+
+ const avgRate =
+ evaluatedCohortsForP > 0 ? periodSumRate / evaluatedCohortsForP : p === 0 ? 100 : 0;
+
+ retentionCurve.push({
+ period: p,
+ periodLabel: periodsHeader[p] || `Period ${p}`,
+ avgRetentionRate: Math.round(avgRate * 10) / 10,
+ totalActiveAccounts: periodTotalActive,
+ evaluatedCohorts: evaluatedCohortsForP,
+ });
+ }
+
+ const stats: CohortSummaryStats = {
+ totalCohorts: cohortRows.length,
+ totalUniqueAccounts: accountFirstSeenMap.size,
+ avgPeriod1Retention: countP1 > 0 ? Math.round((sumP1 / countP1) * 10) / 10 : 0,
+ avgPeriod4Retention: countP4 > 0 ? Math.round((sumP4 / countP4) * 10) / 10 : 0,
+ overallAvgRetention: countOverall > 0 ? Math.round((sumOverall / countOverall) * 10) / 10 : 0,
+ bestCohortKey,
+ retentionCurve,
+ };
+
+ return {
+ ok: true,
+ data: {
+ granularity,
+ activityFilter,
+ cohorts: cohortRows,
+ periodsHeader,
+ stats,
+ generatedAt: new Date().toISOString(),
+ },
+ };
+ } catch (err) {
+ return {
+ ok: false,
+ error: {
+ code: 'CALCULATION_FAILED',
+ message:
+ err instanceof Error
+ ? err.message
+ : 'An unexpected error occurred during cohort calculation.',
+ details: String(err),
+ },
+ };
+ }
+}
+
+// ─── Export Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Converts cohort data snapshot into a clean CSV string.
+ */
+export function exportCohortDataAsCsv(result: CohortRetentionResult): string {
+ if (result.ok === false) {
+ return `Error,${result.error.code},${result.error.message}`;
+ }
+
+ const { cohorts, periodsHeader, granularity } = result.data;
+ const headers = [
+ 'Cohort Key',
+ 'Cohort Label',
+ 'Cohort Start Date',
+ 'Cohort Size (Accounts)',
+ ...periodsHeader.map((p) => `Retention % (${p})`),
+ ];
+
+ const rows = cohorts.map((c) => {
+ return [
+ `"${c.cohortKey}"`,
+ `"${c.cohortLabel}"`,
+ `"${c.cohortStartDate}"`,
+ c.totalAccounts,
+ ...c.retentionByPeriod,
+ ].join(',');
+ });
+
+ return [
+ `# Cohort Retention Report (${granularity.toUpperCase()})`,
+ headers.join(','),
+ ...rows,
+ ].join('\n');
+}
+
+/**
+ * Converts cohort data snapshot into formatted JSON string.
+ */
+export function exportCohortDataAsJson(result: CohortRetentionResult): string {
+ return JSON.stringify(result, null, 2);
+}
+
+// ─── Mock Data Generator for Demos & Testing ─────────────────────────────────
+
+/**
+ * Generates synthetic account activity dataset for testing and demonstration.
+ */
+export function generateMockAccountActivities(
+ accountCount = 80,
+ daysSpan = 60
+): AccountActivityRecord[] {
+ const activities: AccountActivityRecord[] = [];
+ const now = Date.now();
+ const startMs = now - daysSpan * 24 * 60 * 60 * 1000;
+
+ const activityTypes = [
+ 'payment',
+ 'payment',
+ 'invoke_host_function',
+ 'manage_sell_offer',
+ 'create_account',
+ 'change_trust',
+ ];
+
+ for (let i = 0; i < accountCount; i++) {
+ const accountId = `G${String.fromCharCode(65 + (i % 26))}${Math.random().toString(36).slice(2, 9).toUpperCase()}`;
+ // Assign first-seen timestamp evenly across the span
+ const firstSeenMs = startMs + Math.random() * (daysSpan - 14) * 24 * 60 * 60 * 1000;
+
+ // First activity
+ activities.push({
+ accountId,
+ timestamp: new Date(firstSeenMs).toISOString(),
+ activityType: 'create_account',
+ amount: 100,
+ });
+
+ // Simulate retention behavior (different decay patterns for different cohorts)
+ const retentionDecay = 0.4 + Math.random() * 0.5; // 40% - 90% retention decay rate
+ let currentMs = firstSeenMs;
+
+ // Subsequent activities over the remaining time span
+ while (currentMs < now) {
+ // Step forward by 1-7 days
+ currentMs += (1 + Math.random() * 6) * 24 * 60 * 60 * 1000;
+ if (currentMs > now) break;
+
+ // Probabilistic retention check
+ if (Math.random() < retentionDecay) {
+ const type = activityTypes[Math.floor(Math.random() * activityTypes.length)];
+ activities.push({
+ accountId,
+ timestamp: new Date(currentMs).toISOString(),
+ activityType: type,
+ amount: Math.round(Math.random() * 500 * 100) / 100,
+ });
+ }
+ }
+ }
+
+ return activities;
+}
diff --git a/src/lib/costThresholdManager.ts b/src/lib/costThresholdManager.ts
new file mode 100644
index 00000000..541135df
--- /dev/null
+++ b/src/lib/costThresholdManager.ts
@@ -0,0 +1,568 @@
+/**
+ * CostThresholdManager — Application tag & memo prefix cost attribution engine (#868).
+ *
+ * Attributes transaction fees and asset transfer volumes to developer-defined project tags
+ * for project budgeting, cost tracking, and alert threshold monitoring.
+ */
+
+export interface CostTagRule {
+ /** Unique identifier for the rule */
+ id: string
+ /** Human-readable application/project tag (e.g., 'billing', 'auth', 'nft-mint', 'defi-swap') */
+ tag: string
+ /** Optional literal memo prefix string to match (e.g., '[APP:billing]', 'BILL:', 'PAY:') */
+ memoPrefix?: string
+ /** Optional regex pattern string for flexible memo matching (e.g., '^PROJ-[0-9]+') */
+ memoPattern?: string
+ /** Maximum fee budget limit in Stroops for this tag (1 XLM = 10,000,000 Stroops) */
+ budgetLimitStroops?: number
+ /** Maximum volume transfer limit in Stroops for this tag */
+ maxVolumeStroops?: number
+ /** Percentage at which a warning alert is triggered (default: 80) */
+ warningThresholdPercent?: number
+ /** Whether this rule is currently active */
+ enabled: boolean
+}
+
+export interface MatchedTransactionSummary {
+ id: string
+ feeChargedStroops: number
+ volumeStroops: number
+ memo?: string
+ createdAt: string
+ operationCount: number
+}
+
+export interface CostAttributionRecord {
+ /** The application tag name */
+ tag: string
+ /** Rule ID that matched this tag, or 'auto-discovered' if extracted from memo */
+ ruleId: string
+ /** Number of transactions attributed to this tag */
+ transactionCount: number
+ /** Number of operations attributed to this tag */
+ operationCount: number
+ /** Total fees incurred in Stroops */
+ totalFeeStroops: number
+ /** Total fees incurred in XLM */
+ totalFeeXlm: number
+ /** Average fee per transaction in Stroops */
+ averageFeeStroops: number
+ /** Total payment / asset volume transferred in Stroops */
+ totalVolumeStroops: number
+ /** Total payment / asset volume transferred in XLM */
+ totalVolumeXlm: number
+ /** Configured fee budget limit in Stroops (if any) */
+ budgetLimitStroops?: number
+ /** Configured fee budget limit in XLM (if any) */
+ budgetLimitXlm?: number
+ /** Percentage of budget consumed */
+ budgetUsedPercent: number
+ /** Budget health status */
+ status: 'ok' | 'warning' | 'exceeded' | 'unbudgeted'
+ /** List of transactions matching this tag */
+ matchedTransactions: MatchedTransactionSummary[]
+}
+
+export interface CostThresholdAlert {
+ id: string
+ tag: string
+ severity: 'warning' | 'exceeded'
+ message: string
+ budgetPercent: number
+ currentFeeStroops: number
+ budgetLimitStroops: number
+}
+
+export interface CostAttributionSummary {
+ /** Total fee in Stroops across all attributed transactions */
+ totalAttributedFeeStroops: number
+ /** Total fee in XLM across all attributed transactions */
+ totalAttributedFeeXlm: number
+ /** Total fee in Stroops for transactions that didn't match any tag */
+ totalUnattributedFeeStroops: number
+ /** Total fee in XLM for transactions that didn't match any tag */
+ totalUnattributedFeeXlm: number
+ /** Total transaction count evaluated */
+ totalTransactions: number
+ /** Total operation count evaluated */
+ totalOperations: number
+ /** Per-tag attribution breakdown */
+ tagBreakdown: CostAttributionRecord[]
+ /** Active budget threshold alerts */
+ thresholdAlerts: CostThresholdAlert[]
+ /** ISO timestamp of analysis */
+ generatedAt: string
+ /** Non-fatal warning messages for malformed input records */
+ warnings?: string[]
+}
+
+export interface TransactionInput {
+ id?: string
+ hash?: string
+ fee_charged?: string | number
+ feeCharged?: string | number
+ fee?: string | number
+ memo?: string | null
+ memo_type?: string
+ created_at?: string
+ createdAt?: string
+ operation_count?: number
+ operationCount?: number
+ successful?: boolean
+ operations?: Array<{
+ amount?: string | number
+ starting_balance?: string | number
+ startingBalance?: string | number
+ [key: string]: unknown
+ }>
+ [key: string]: unknown
+}
+
+const STORAGE_KEY = 'stellar_cost_threshold_rules_v1'
+const STROOPS_PER_XLM = 10_000_000
+
+/**
+ * Normalizes input numeric values safely to finite non-negative numbers.
+ */
+function parseStroops(value: unknown): number {
+ if (value === null || value === undefined) return 0
+ const parsed = typeof value === 'number' ? value : parseFloat(String(value))
+ if (isNaN(parsed) || !isFinite(parsed) || parsed < 0) return 0
+ return Math.round(parsed)
+}
+
+/**
+ * Extracts volume in Stroops from transaction operations or attributes.
+ */
+function extractTransactionVolume(tx: TransactionInput): number {
+ let volume = 0
+ if (Array.isArray(tx.operations)) {
+ for (const op of tx.operations) {
+ if (!op || typeof op !== 'object') continue
+ if ('amount' in op) {
+ volume += parseStroops(op.amount)
+ } else if ('starting_balance' in op) {
+ volume += parseStroops(op.starting_balance)
+ } else if ('startingBalance' in op) {
+ volume += parseStroops(op.startingBalance)
+ }
+ }
+ }
+ return volume
+}
+
+/**
+ * Auto-detects application tag from memo text if structured like [APP:tag] or APP:tag:
+ */
+function extractAutoTag(memo: string | null | undefined): string | null {
+ if (!memo || typeof memo !== 'string') return null
+ const trimmed = memo.trim()
+
+ // Match [APP:tag] or [TAG:tag] or [PROJ:tag]
+ const bracketMatch = trimmed.match(/^\[(?:APP|TAG|PROJ):([a-zA-Z0-9_-]+)\]/i)
+ if (bracketMatch) return bracketMatch[1].toLowerCase()
+
+ // Match APP:tag or TAG:tag prefix
+ const prefixMatch = trimmed.match(/^(?:APP|TAG|PROJ):([a-zA-Z0-9_-]+)(?::|\s|$)/i)
+ if (prefixMatch) return prefixMatch[1].toLowerCase()
+
+ return null
+}
+
+export class CostThresholdManager {
+ private rules: Map = new Map()
+ private storageKey: string
+
+ constructor(initialRules?: CostTagRule[], storageKey = STORAGE_KEY) {
+ this.storageKey = storageKey
+ this.loadRules(initialRules)
+ }
+
+ /**
+ * Safe storage reader handling unsupported environments (SSR, privacy mode, restricted iframe).
+ */
+ private loadRules(fallbackRules?: CostTagRule[]): void {
+ let loaded = false
+ try {
+ if (typeof window !== 'undefined' && window.localStorage) {
+ const raw = window.localStorage.getItem(this.storageKey)
+ if (raw) {
+ const parsed = JSON.parse(raw)
+ if (Array.isArray(parsed)) {
+ parsed.forEach((rule) => {
+ if (rule && typeof rule === 'object' && rule.id && rule.tag) {
+ this.rules.set(rule.id, this.normalizeRule(rule))
+ }
+ })
+ loaded = true
+ }
+ }
+ }
+ } catch {
+ // Storage unavailable or blocked
+ }
+
+ if (!loaded && fallbackRules && Array.isArray(fallbackRules)) {
+ fallbackRules.forEach((rule) => {
+ if (rule && typeof rule === 'object' && rule.tag) {
+ const normalized = this.normalizeRule(rule)
+ this.rules.set(normalized.id, normalized)
+ }
+ })
+ }
+ }
+
+ /**
+ * Safe storage writer handling storage failure or quota errors.
+ */
+ private persistRules(): void {
+ try {
+ if (typeof window !== 'undefined' && window.localStorage) {
+ const rulesArray = Array.from(this.rules.values())
+ window.localStorage.setItem(this.storageKey, JSON.stringify(rulesArray))
+ }
+ } catch {
+ // Gracefully ignore storage write failures in restricted environments
+ }
+ }
+
+ private normalizeRule(input: Partial & { tag: string }): CostTagRule {
+ const id = input.id && typeof input.id === 'string' ? input.id : `rule_${Date.now()}_${Math.random().toString(36).substring(2, 7)}`
+ const tag = String(input.tag).trim().toLowerCase() || 'default'
+ const warningThresholdPercent = typeof input.warningThresholdPercent === 'number' && !isNaN(input.warningThresholdPercent)
+ ? Math.max(1, Math.min(100, input.warningThresholdPercent))
+ : 80
+
+ return {
+ id,
+ tag,
+ memoPrefix: input.memoPrefix ? String(input.memoPrefix) : undefined,
+ memoPattern: input.memoPattern ? String(input.memoPattern) : undefined,
+ budgetLimitStroops: typeof input.budgetLimitStroops === 'number' && input.budgetLimitStroops >= 0 ? input.budgetLimitStroops : undefined,
+ maxVolumeStroops: typeof input.maxVolumeStroops === 'number' && input.maxVolumeStroops >= 0 ? input.maxVolumeStroops : undefined,
+ warningThresholdPercent,
+ enabled: input.enabled !== false,
+ }
+ }
+
+ /**
+ * Adds a new cost threshold rule.
+ */
+ public addRule(rule: Partial & { tag: string }): CostTagRule {
+ if (!rule || typeof rule !== 'object' || !rule.tag) {
+ throw new Error('Invalid rule input: tag is required')
+ }
+ const normalized = this.normalizeRule(rule)
+ this.rules.set(normalized.id, normalized)
+ this.persistRules()
+ return normalized
+ }
+
+ /**
+ * Updates an existing rule.
+ */
+ public updateRule(id: string, updates: Partial): CostTagRule | null {
+ if (!id || !this.rules.has(id)) return null
+ const existing = this.rules.get(id)!
+ const updated = this.normalizeRule({ ...existing, ...updates, id })
+ this.rules.set(id, updated)
+ this.persistRules()
+ return updated
+ }
+
+ /**
+ * Removes a rule by ID.
+ */
+ public removeRule(id: string): boolean {
+ const deleted = this.rules.delete(id)
+ if (deleted) this.persistRules()
+ return deleted
+ }
+
+ /**
+ * Returns all active rules.
+ */
+ public getRules(): CostTagRule[] {
+ return Array.from(this.rules.values())
+ }
+
+ /**
+ * Replaces all rules.
+ */
+ public setRules(rules: CostTagRule[]): void {
+ this.rules.clear()
+ if (Array.isArray(rules)) {
+ rules.forEach((r) => {
+ if (r && r.tag) {
+ const norm = this.normalizeRule(r)
+ this.rules.set(norm.id, norm)
+ }
+ })
+ }
+ this.persistRules()
+ }
+
+ /**
+ * Clears all rules.
+ */
+ public clearRules(): void {
+ this.rules.clear()
+ this.persistRules()
+ }
+
+ /**
+ * Evaluates if a memo matches a rule (prefix or pattern).
+ */
+ private matchRule(memo: string, rule: CostTagRule): boolean {
+ if (!rule.enabled) return false
+ const trimmedMemo = memo.trim()
+
+ if (rule.memoPrefix && trimmedMemo.startsWith(rule.memoPrefix)) {
+ return true
+ }
+
+ if (rule.memoPattern) {
+ try {
+ const regex = new RegExp(rule.memoPattern, 'i')
+ if (regex.test(trimmedMemo)) return true
+ } catch {
+ // Safe regex failure path handling malformed regex
+ }
+ }
+
+ // Exact tag match if tag is embedded in memo
+ if (trimmedMemo.toLowerCase().includes(rule.tag.toLowerCase())) {
+ return true
+ }
+
+ return false
+ }
+
+ /**
+ * Attributes transactions and payment volumes to application tags / memo prefixes.
+ */
+ public attributeTransactions(
+ transactions: TransactionInput[] | null | undefined
+ ): CostAttributionSummary {
+ const warnings: string[] = []
+
+ if (!transactions || !Array.isArray(transactions)) {
+ return {
+ totalAttributedFeeStroops: 0,
+ totalAttributedFeeXlm: 0,
+ totalUnattributedFeeStroops: 0,
+ totalUnattributedFeeXlm: 0,
+ totalTransactions: 0,
+ totalOperations: 0,
+ tagBreakdown: [],
+ thresholdAlerts: [],
+ generatedAt: new Date().toISOString(),
+ warnings: ['Input transactions was empty or not an array.'],
+ }
+ }
+
+ const activeRules = Array.from(this.rules.values()).filter((r) => r.enabled)
+ const breakdownMap = new Map()
+ const alerts: CostThresholdAlert[] = []
+
+ let totalAttributedFee = 0
+ let totalUnattributedFee = 0
+ let totalOperationsEvaluated = 0
+
+ transactions.forEach((tx, idx) => {
+ if (!tx || typeof tx !== 'object') {
+ warnings.push(`Skipped invalid transaction object at index ${idx}`)
+ return
+ }
+
+ const txId = tx.id || tx.hash || `tx_${idx}`
+ const feeStroops = parseStroops(tx.fee_charged ?? tx.feeCharged ?? tx.fee)
+ const opCount = typeof tx.operation_count === 'number'
+ ? tx.operation_count
+ : typeof tx.operationCount === 'number'
+ ? tx.operationCount
+ : Array.isArray(tx.operations) ? tx.operations.length : 1
+
+ totalOperationsEvaluated += opCount
+ const volumeStroops = extractTransactionVolume(tx)
+ const memo = typeof tx.memo === 'string' ? tx.memo : undefined
+ const createdAt = tx.created_at || tx.createdAt || new Date().toISOString()
+
+ let matchedRule: CostTagRule | null = null
+
+ // First check defined rules
+ if (memo) {
+ for (const rule of activeRules) {
+ if (this.matchRule(memo, rule)) {
+ matchedRule = rule
+ break
+ }
+ }
+ }
+
+ // If no explicit rule matched, attempt auto-tag extraction from memo
+ let tagKey: string | null = matchedRule ? matchedRule.tag : null
+ let ruleId: string = matchedRule ? matchedRule.id : 'auto-discovered'
+
+ if (!tagKey && memo) {
+ const autoTag = extractAutoTag(memo)
+ if (autoTag) {
+ tagKey = autoTag
+ ruleId = 'auto-discovered'
+ }
+ }
+
+ const txSummary: MatchedTransactionSummary = {
+ id: txId,
+ feeChargedStroops: feeStroops,
+ volumeStroops,
+ memo,
+ createdAt,
+ operationCount: opCount,
+ }
+
+ if (tagKey) {
+ totalAttributedFee += feeStroops
+ let record = breakdownMap.get(tagKey)
+
+ if (!record) {
+ record = {
+ tag: tagKey,
+ ruleId,
+ transactionCount: 0,
+ operationCount: 0,
+ totalFeeStroops: 0,
+ totalFeeXlm: 0,
+ averageFeeStroops: 0,
+ totalVolumeStroops: 0,
+ totalVolumeXlm: 0,
+ budgetLimitStroops: matchedRule?.budgetLimitStroops,
+ budgetLimitXlm: matchedRule?.budgetLimitStroops ? matchedRule.budgetLimitStroops / STROOPS_PER_XLM : undefined,
+ budgetUsedPercent: 0,
+ status: matchedRule?.budgetLimitStroops ? 'ok' : 'unbudgeted',
+ matchedTransactions: [],
+ }
+ breakdownMap.set(tagKey, record)
+ }
+
+ record.transactionCount += 1
+ record.operationCount += opCount
+ record.totalFeeStroops += feeStroops
+ record.totalFeeXlm = record.totalFeeStroops / STROOPS_PER_XLM
+ record.averageFeeStroops = Math.round(record.totalFeeStroops / record.transactionCount)
+ record.totalVolumeStroops += volumeStroops
+ record.totalVolumeXlm = record.totalVolumeStroops / STROOPS_PER_XLM
+ record.matchedTransactions.push(txSummary)
+
+ // Calculate budget percentage and threshold status
+ if (record.budgetLimitStroops && record.budgetLimitStroops > 0) {
+ const percent = (record.totalFeeStroops / record.budgetLimitStroops) * 100
+ record.budgetUsedPercent = Math.round(percent * 10) / 10
+
+ const warningThreshold = matchedRule?.warningThresholdPercent ?? 80
+
+ if (percent >= 100) {
+ record.status = 'exceeded'
+ alerts.push({
+ id: `alert_exceeded_${tagKey}`,
+ tag: tagKey,
+ severity: 'exceeded',
+ message: `Tag '${tagKey}' has exceeded its budget limit of ${(record.budgetLimitStroops / STROOPS_PER_XLM).toFixed(2)} XLM (${record.budgetUsedPercent}% used).`,
+ budgetPercent: record.budgetUsedPercent,
+ currentFeeStroops: record.totalFeeStroops,
+ budgetLimitStroops: record.budgetLimitStroops,
+ })
+ } else if (percent >= warningThreshold) {
+ record.status = 'warning'
+ alerts.push({
+ id: `alert_warning_${tagKey}`,
+ tag: tagKey,
+ severity: 'warning',
+ message: `Tag '${tagKey}' has reached ${record.budgetUsedPercent}% of its budget limit.`,
+ budgetPercent: record.budgetUsedPercent,
+ currentFeeStroops: record.totalFeeStroops,
+ budgetLimitStroops: record.budgetLimitStroops,
+ })
+ } else {
+ record.status = 'ok'
+ }
+ }
+ } else {
+ totalUnattributedFee += feeStroops
+ }
+ })
+
+ const tagBreakdown = Array.from(breakdownMap.values()).sort(
+ (a, b) => b.totalFeeStroops - a.totalFeeStroops
+ )
+
+ return {
+ totalAttributedFeeStroops: totalAttributedFee,
+ totalAttributedFeeXlm: totalAttributedFee / STROOPS_PER_XLM,
+ totalUnattributedFeeStroops: totalUnattributedFee,
+ totalUnattributedFeeXlm: totalUnattributedFee / STROOPS_PER_XLM,
+ totalTransactions: transactions.length,
+ totalOperations: totalOperationsEvaluated,
+ tagBreakdown,
+ thresholdAlerts: alerts,
+ generatedAt: new Date().toISOString(),
+ warnings: warnings.length > 0 ? warnings : undefined,
+ }
+ }
+
+ /**
+ * Formats a cost attribution summary as JSON or CSV export text.
+ */
+ public exportAttributionReport(
+ summary: CostAttributionSummary,
+ format: 'csv' | 'json' = 'json'
+ ): string {
+ if (!summary || typeof summary !== 'object') {
+ return format === 'json' ? '{}' : ''
+ }
+
+ if (format === 'json') {
+ return JSON.stringify(summary, null, 2)
+ }
+
+ const headers = [
+ 'Tag',
+ 'Rule ID',
+ 'Transactions',
+ 'Operations',
+ 'Total Fee (Stroops)',
+ 'Total Fee (XLM)',
+ 'Avg Fee (Stroops)',
+ 'Volume (XLM)',
+ 'Budget Limit (XLM)',
+ 'Budget Used (%)',
+ 'Status',
+ ]
+
+ const rows = (summary.tagBreakdown || []).map((b) => [
+ `"${b.tag}"`,
+ `"${b.ruleId}"`,
+ b.transactionCount,
+ b.operationCount,
+ b.totalFeeStroops,
+ b.totalFeeXlm.toFixed(7),
+ b.averageFeeStroops,
+ b.totalVolumeXlm.toFixed(7),
+ b.budgetLimitXlm !== undefined ? b.budgetLimitXlm.toFixed(2) : 'N/A',
+ `${b.budgetUsedPercent}%`,
+ b.status,
+ ])
+
+ return [headers.join(','), ...rows.map((r) => r.join(','))].join('\n')
+ }
+}
+
+let defaultManager: CostThresholdManager | null = null
+
+export function getCostThresholdManager(): CostThresholdManager {
+ if (!defaultManager) {
+ defaultManager = new CostThresholdManager()
+ }
+ return defaultManager
+}
diff --git a/src/routes/routes.ts b/src/routes/routes.ts
index db8ca179..11c85048 100644
--- a/src/routes/routes.ts
+++ b/src/routes/routes.ts
@@ -26,10 +26,7 @@ export type RouteLoader = () => Promise<{ default: TabComponent }>;
/** Sidebar grouping keys. `SYSTEM` exists for views that are routed but not shown in the sidebar. */
export type RouteGroup =
- | 'explore'
- | 'build'
- | 'monitor'
- | 'admin';
+ 'analytics' | 'network' | 'build' | 'explore' | 'payments' | 'tools' | 'system';
/** Metadata for entity views that expose a URL path parameter. */
export interface RouteParam {
@@ -69,15 +66,12 @@ export interface AppRoute {
// ─── Loader helpers ───────────────────────────────────────────────────────────
-const defaultLoader = (
- loader: () => Promise<{ default: TabComponent }>,
-): RouteLoader => loader;
+const defaultLoader = (loader: () => Promise<{ default: TabComponent }>): RouteLoader => loader;
-const namedLoader = (
- loader: () => Promise>,
- exportName: string,
-): RouteLoader => () =>
- loader().then((module) => ({ default: module[exportName] as TabComponent }));
+const namedLoader =
+ (loader: () => Promise>, exportName: string): RouteLoader =>
+ () =>
+ loader().then((module) => ({ default: module[exportName] as TabComponent }));
// ─── Registry ─────────────────────────────────────────────────────────────────
// Order matters: it defines sidebar order within each group and match priority.
@@ -262,7 +256,10 @@ export const ROUTES: AppRoute[] = [
title: 'Soroban Debugging',
icon: '🐞',
group: 'build',
- loader: namedLoader(() => import('../components/dashboard/SorobanDebugTutorial'), 'SorobanDebugTutorial'),
+ loader: namedLoader(
+ () => import('../components/dashboard/SorobanDebugTutorial'),
+ 'SorobanDebugTutorial'
+ ),
},
{
id: 'learningHub',
@@ -450,6 +447,14 @@ export const ROUTES: AppRoute[] = [
group: 'monitor',
loader: defaultLoader(() => import('../components/dashboard/Analytics')),
},
+ {
+ id: 'cohortRetention',
+ path: '/cohortRetention',
+ title: 'Cohort Retention',
+ icon: '👥',
+ group: 'analytics',
+ loader: defaultLoader(() => import('../components/dashboard/CohortRetentionView')),
+ },
{
id: 'designSystem',
path: '/designSystem',
@@ -660,7 +665,7 @@ export const ROUTES_BY_ID: Record = Object.freeze(
ROUTES.reduce>((acc, route) => {
acc[route.id] = route;
return acc;
- }, {}),
+ }, {})
);
export const GROUP_LABELS: Record = {
@@ -715,8 +720,8 @@ const MOBILE_NAV_IDS = [
] as const;
export function getMobileNavRoutes(): AppRoute[] {
- return MOBILE_NAV_IDS.map((id) => ROUTES_BY_ID[id]).filter(
- (route): route is AppRoute => Boolean(route),
+ return MOBILE_NAV_IDS.map((id) => ROUTES_BY_ID[id]).filter((route): route is AppRoute =>
+ Boolean(route)
);
}
@@ -769,10 +774,7 @@ export interface RouteVisibilityOptions {
* `minExpertise` / `featureFlag` always pass, so the default sidebar is
* unchanged for existing users.
*/
-export function isRouteVisible(
- route: AppRoute,
- options: RouteVisibilityOptions = {},
-): boolean {
+export function isRouteVisible(route: AppRoute, options: RouteVisibilityOptions = {}): boolean {
if (route.minExpertise && options.expertiseLevel) {
if (LEVEL_RANK[options.expertiseLevel] < LEVEL_RANK[route.minExpertise]) {
return false;
@@ -793,19 +795,13 @@ export function isRouteVisible(
* buildPath('account', { address: 'G...' }) // → '/account/G...'
* buildPath('account') // → '/account' (optional param omitted)
*/
-export function buildPath(
- id: string,
- params: Record = {},
-): string {
+export function buildPath(id: string, params: Record = {}): string {
const route = ROUTES_BY_ID[id];
if (!route) return '/';
let path = route.path;
for (const [key, value] of Object.entries(params)) {
if (value === undefined || value === null || value === '') continue;
- path = path.replace(
- new RegExp(`:${key}\\??`),
- encodeURIComponent(String(value)),
- );
+ path = path.replace(new RegExp(`:${key}\\??`), encodeURIComponent(String(value)));
}
// Drop any optional segments the caller did not supply.
path = path.replace(/\/:[^/]+\?/g, '');