@happyvertical/smrt-sales 0.39.2

package/dist/svelte/types.js

@@ -0,0 +1,376 @@
+/**
+ * Presentational view models and pure helpers for the sales Svelte surfaces.
+ *
+ * The components are props-driven and presentational: hosts map their model
+ * rows (CRM, referrals, commissions) onto these plain view-model interfaces
+ * and wire the action callbacks. Only STATUS UNIONS are imported from the
+ * sibling TS modules — type-only, so the compiled Svelte bundle never gains a
+ * runtime dependency on the model/collection code. Monetary fields stay
+ * integer cents in every view model; conversion to display strings happens at
+ * render time via `format.ts`.
+ *
+ * Dashboard math, award validation, and status flows live here as exported
+ * pure functions so they are unit-testable without mounting components.
+ *
+ * @module
+ */
+import { formatCents, formatPercent } from './format.js';
+// ─────────────────────────────────────────────────────────────────────────────
+// Status → badge-variant mappers (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+/** Badge variant for a Lead lifecycle status. */
+export function leadStatusBadgeVariant(status) {
+    switch (status) {
+        case 'new':
+            return 'info';
+        case 'working':
+            return 'primary';
+        case 'qualified':
+            return 'success';
+        case 'disqualified':
+            return 'error';
+        default:
+            return 'default';
+    }
+}
+/** Badge variant for an Opportunity lifecycle status. */
+export function opportunityStatusBadgeVariant(status) {
+    switch (status) {
+        case 'won':
+            return 'success';
+        case 'lost':
+            return 'error';
+        default:
+            return 'info';
+    }
+}
+/** Badge variant for a Referral lifecycle status. */
+export function referralStatusBadgeVariant(status) {
+    switch (status) {
+        case 'attributed':
+            return 'info';
+        case 'qualified':
+            return 'success';
+        case 'disqualified':
+            return 'error';
+        case 'expired':
+            return 'warning';
+        case 'under_review':
+            return 'warning';
+        default:
+            return 'default';
+    }
+}
+/** Badge variant for a ReferralLink status. */
+export function referralLinkStatusBadgeVariant(status) {
+    return status === 'active' ? 'success' : 'default';
+}
+/** Badge variant for a Commission settlement-chain status. */
+export function commissionStatusBadgeVariant(status) {
+    switch (status) {
+        case 'earned':
+            return 'info';
+        case 'approved':
+            return 'primary';
+        case 'payable':
+            return 'warning';
+        case 'paid':
+            return 'success';
+        default:
+            return 'default';
+    }
+}
+/** Badge variant for a CommissionPayout batch status. */
+export function payoutStatusBadgeVariant(status) {
+    switch (status) {
+        case 'approved':
+            return 'info';
+        case 'processing':
+            return 'warning';
+        case 'completed':
+            return 'success';
+        case 'failed':
+            return 'error';
+        default:
+            return 'default';
+    }
+}
+/** Badge variant for a ReferralAgreement version status. */
+export function agreementStatusBadgeVariant(status) {
+    switch (status) {
+        case 'active':
+            return 'success';
+        case 'superseded':
+            return 'warning';
+        case 'terminated':
+            return 'error';
+        default:
+            return 'default';
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// CRM helpers (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Whether the qualify action applies to a lead in `status` — mirrors the
+ * `new|working → qualified` transitions guarded by the Lead model.
+ */
+export function canQualifyLead(status) {
+    return status === 'new' || status === 'working';
+}
+/** Whether a next action is overdue relative to `now` (default: current time). */
+export function isOverdue(dueAt, now = new Date()) {
+    if (dueAt == null || dueAt === '')
+        return false;
+    const due = dueAt instanceof Date ? dueAt : new Date(dueAt);
+    if (Number.isNaN(due.getTime()))
+        return false;
+    return due.getTime() < now.getTime();
+}
+/** Count of opportunities still `open`. */
+export function openOpportunityCount(opportunities) {
+    return opportunities.filter((o) => o.status === 'open').length;
+}
+/**
+ * Total expected value of OPEN opportunities, grouped per currency (sorted by
+ * currency code) — currencies are never summed together.
+ */
+export function openPipelineTotals(opportunities) {
+    const totals = new Map();
+    for (const opportunity of opportunities) {
+        if (opportunity.status !== 'open')
+            continue;
+        totals.set(opportunity.currency, (totals.get(opportunity.currency) ?? 0) + opportunity.expectedValueCents);
+    }
+    return [...totals.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([currency, amountCents]) => ({ currency, amountCents }));
+}
+/**
+ * Open-pipeline expected value per stage, in the given stage order. Terminal
+ * stages report zero (their opportunities are no longer `open`).
+ */
+export function pipelineValueByStage(stages, opportunities) {
+    return stages.map((stage) => {
+        const open = opportunities.filter((o) => o.stageId === stage.id && o.status === 'open');
+        return {
+            stageId: stage.id,
+            stageName: stage.name,
+            openCount: open.length,
+            totals: openPipelineTotals(open),
+        };
+    });
+}
+/**
+ * Win rate over CLOSED opportunities: `won / (won + lost)`, or `null` when
+ * nothing has closed yet (so the tile can render a placeholder, not `0%`).
+ */
+export function winRate(opportunities) {
+    let won = 0;
+    let lost = 0;
+    for (const opportunity of opportunities) {
+        if (opportunity.status === 'won')
+            won += 1;
+        else if (opportunity.status === 'lost')
+            lost += 1;
+    }
+    const closed = won + lost;
+    return closed === 0 ? null : won / closed;
+}
+/**
+ * Group opportunities into the given stage order for the board. Opportunities
+ * pointing at a stage not present in `stages` are omitted — the board renders
+ * exactly the columns it is given.
+ */
+export function groupOpportunitiesByStage(stages, opportunities) {
+    return stages.map((stage) => ({
+        stage,
+        opportunities: opportunities.filter((o) => o.stageId === stage.id),
+    }));
+}
+/** Neighbouring stage ids for keyboard-accessible next/prev stage movement. */
+export function adjacentStageIds(stages, stageId) {
+    const index = stages.findIndex((stage) => stage.id === stageId);
+    if (index === -1)
+        return { prevStageId: null, nextStageId: null };
+    return {
+        prevStageId: index > 0 ? stages[index - 1].id : null,
+        nextStageId: index < stages.length - 1 ? stages[index + 1].id : null,
+    };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Referral helpers (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Share URL for a referral code: `<shareBaseUrl>/<code>` (trailing slashes on
+ * the base are normalised; the code is URL-encoded).
+ */
+export function buildShareUrl(shareBaseUrl, code) {
+    const base = shareBaseUrl.replace(/\/+$/, '');
+    return `${base}/${encodeURIComponent(code)}`;
+}
+/** Loose http(s) URL check used to gate the create-link form. */
+export function isHttpUrl(value) {
+    return /^https?:\/\/\S+$/i.test(value.trim());
+}
+/**
+ * Tolerance for award credit fractions summing to 1.0 — mirrors
+ * `AttributionService.assertAwards` (±0.0001).
+ */
+export const AWARD_FRACTION_TOLERANCE = 0.0001;
+/**
+ * Validate an award draft the way `AttributionService.resolveException` will:
+ * at least one award, distinct referrers, every fraction in (0, 1], and the
+ * fractions summing to 1.0 (±{@link AWARD_FRACTION_TOLERANCE}).
+ */
+export function validateAwards(awards) {
+    if (awards.length === 0) {
+        return {
+            valid: false,
+            totalFraction: 0,
+            message: 'At least one award is required.',
+        };
+    }
+    const seen = new Set();
+    let sum = 0;
+    for (const award of awards) {
+        if (!award.referrerId) {
+            return {
+                valid: false,
+                totalFraction: sum,
+                message: 'Every award needs a referrer.',
+            };
+        }
+        if (seen.has(award.referrerId)) {
+            return {
+                valid: false,
+                totalFraction: sum,
+                message: 'Each referrer may receive at most one award.',
+            };
+        }
+        seen.add(award.referrerId);
+        if (!Number.isFinite(award.creditFraction) ||
+            award.creditFraction <= 0 ||
+            award.creditFraction > 1) {
+            return {
+                valid: false,
+                totalFraction: sum,
+                message: 'Each credit fraction must be greater than 0 and at most 1.',
+            };
+        }
+        sum += award.creditFraction;
+    }
+    if (Math.abs(sum - 1) > AWARD_FRACTION_TOLERANCE) {
+        return {
+            valid: false,
+            totalFraction: sum,
+            message: `Credit fractions must sum to 100% — currently ${formatPercent(sum)}.`,
+        };
+    }
+    return { valid: true, totalFraction: sum };
+}
+/** Distinct candidate referrer ids, in first-seen order. */
+export function uniqueCandidateReferrerIds(candidates) {
+    const ids = [];
+    const seen = new Set();
+    for (const candidate of candidates) {
+        if (seen.has(candidate.referrerId))
+            continue;
+        seen.add(candidate.referrerId);
+        ids.push(candidate.referrerId);
+    }
+    return ids;
+}
+/**
+ * Seed an equal split across `referrerIds`, rounded to 4 decimal places with
+ * the LAST share adjusted so the set sums to exactly 1.0 (mirrors the
+ * AttributionService split convention).
+ */
+export function equalSplitAwards(referrerIds) {
+    const count = referrerIds.length;
+    if (count === 0)
+        return [];
+    const share = Math.round(10000 / count) / 10000;
+    return referrerIds.map((referrerId, index) => ({
+        referrerId,
+        creditFraction: index === count - 1
+            ? Math.round((1 - share * (count - 1)) * 10000) / 10000
+            : share,
+    }));
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Commission / settlement helpers (pure)
+// ─────────────────────────────────────────────────────────────────────────────
+/** `planKey@vN` display reference for snapshotted plan versions. */
+export function formatPlanRef(planKey, planVersion) {
+    return `${planKey}@v${planVersion}`;
+}
+/**
+ * Render the snapshotted calculation as a one-line formula. Fixed-basis
+ * components have no rate factor (`rate` is recorded as `0`), so the line
+ * becomes `base (fixed) × share = amount`.
+ */
+export function formatCommissionFormula(parts, locale) {
+    const base = formatCents(parts.baseAmountCents, parts.currency, locale);
+    const share = formatPercent(parts.shareFraction, locale);
+    const amount = formatCents(parts.amountCents, parts.currency, locale);
+    if (parts.basis === 'fixed') {
+        return `${base} (fixed) × ${share} = ${amount}`;
+    }
+    return `${base} × ${formatPercent(parts.rate, locale)} × ${share} = ${amount}`;
+}
+/**
+ * Linear settlement timeline for a payout batch. The happy path is
+ * `pending → approved → processing → completed`; for a `failed` batch the
+ * terminal marker replaces `completed`.
+ */
+export function payoutStatusTimeline(status) {
+    const path = status === 'failed'
+        ? ['pending', 'approved', 'processing', 'failed']
+        : ['pending', 'approved', 'processing', 'completed'];
+    const index = path.indexOf(status);
+    return path.map((step, i) => ({
+        status: step,
+        state: i < index ? 'done' : i === index ? 'current' : 'upcoming',
+    }));
+}
+/**
+ * Action gating for {@link PayoutBatchReview}, mirroring the CommissionPayout
+ * transition guard: `pending → approved → processing → completed | failed`,
+ * with `failed` reachable from `approved`/`processing`.
+ */
+export function payoutActionsFor(status) {
+    return {
+        canApprove: status === 'pending',
+        canMarkProcessing: status === 'approved',
+        canComplete: status === 'processing',
+        canFail: status === 'approved' || status === 'processing',
+    };
+}
+/**
+ * Sum reconciliation rows per currency (sorted by currency code). Currencies
+ * are never summed together.
+ */
+export function sumExpenseRowsByCurrency(rows) {
+    const byCurrency = new Map();
+    for (const row of rows) {
+        const entry = byCurrency.get(row.currency) ?? {
+            expense: 0,
+            adjustments: 0,
+            payouts: 0,
+        };
+        entry.expense += row.commissionExpenseCents;
+        entry.adjustments += row.adjustmentCents;
+        entry.payouts += row.payoutCents;
+        byCurrency.set(row.currency, entry);
+    }
+    return [...byCurrency.entries()]
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([currency, { expense, adjustments, payouts }]) => ({
+        currency,
+        commissionExpenseCents: expense,
+        adjustmentCents: adjustments,
+        payoutCents: payouts,
+        netAccruedCents: expense + adjustments - payouts,
+    }));
+}

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "@happyvertical/smrt-sales",
+  "version": "0.39.2",
+  "description": "Modular sales for the SMRT framework: CRM (Leads, Opportunities, Pipelines), referral intake with versioned attribution policies, neutral commissions with snapshots and payouts, and reusable Svelte surfaces",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "CLAUDE.md",
+    "AGENTS.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./crm": {
+      "types": "./dist/crm.d.ts",
+      "import": "./dist/crm.js"
+    },
+    "./referrals": {
+      "types": "./dist/referrals.d.ts",
+      "import": "./dist/referrals.js"
+    },
+    "./commissions": {
+      "types": "./dist/commissions.d.ts",
+      "import": "./dist/commissions.js"
+    },
+    "./svelte": {
+      "types": "./dist/svelte/index.d.ts",
+      "svelte": "./dist/svelte/index.js",
+      "import": "./dist/svelte/index.js"
+    },
+    "./manifest": "./dist/manifest.json",
+    "./manifest.json": "./dist/manifest.json"
+  },
+  "dependencies": {
+    "@happyvertical/sql": "^0.78.0",
+    "@happyvertical/smrt-core": "0.39.2",
+    "@happyvertical/smrt-tenancy": "0.39.2",
+    "@happyvertical/smrt-ui": "0.39.2"
+  },
+  "peerDependencies": {
+    "svelte": "^5.56.4"
+  },
+  "devDependencies": {
+    "@sveltejs/package": "^2.5.8",
+    "@sveltejs/vite-plugin-svelte": "^7.1.2",
+    "@types/node": "24.13.2",
+    "svelte": "^5.56.4",
+    "svelte-check": "^4.7.1",
+    "typescript": "^5.9.3",
+    "vite": "^8.1.3",
+    "vitest": "^4.1.9",
+    "@happyvertical/smrt-vitest": "0.39.2"
+  },
+  "smrtRawPrimitives": "strict",
+  "keywords": [
+    "smrt",
+    "sales",
+    "crm",
+    "referrals",
+    "commissions",
+    "payouts",
+    "multi-tenant"
+  ],
+  "author": "HappyVertical",
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/happyvertical/smrt.git",
+    "directory": "packages/sales"
+  },
+  "scripts": {
+    "build": "vite build --mode library && svelte-package -i src/svelte -o dist/svelte --tsconfig tsconfig.svelte.json",
+    "build:watch": "vite build --mode library --watch",
+    "clean": "rm -rf dist",
+    "dev": "vite dev",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit -p tsconfig.json && node ../../scripts/svelte-check-a11y.mjs --tsconfig ./tsconfig.svelte.json",
+    "verify:pack": "node ../../scripts/verify-package-types-exports.js ."
+  }
+}