@happyvertical/smrt-sales

中文文档
0.62.1发布于 2026/11/17MITTypeScriptES Module近 30 天下载 1.5万

Modular sales for the SMRT framework: agreement execution, CRM, referral intake, neutral commissions, and reusable Svelte surfaces

原始使用文档
文档目录13 节
  1. Installation
  2. Modules
  3. Quick start: commission terms
  4. Waterfall plans
  5. Pool recipients
  6. Organisation and treasury earners
  7. Core model
  8. Referrer nominations
  9. Lead intake and lifecycle
  10. Agreement boundary
  11. Tenancy and cross-package references
  12. Migration from affiliates
  13. Development

@happyvertical/smrt-sales

Provider-neutral sales operations for s-m-r-t: agreement execution, CRM, referral intake and attribution, a neutral commissions core, and reusable Svelte surfaces. It is one installable package with subpaths that keep consumers scoped to the modules they use.

@happyvertical/smrt-affiliates is a deprecated compatibility shim over the commissions module. New applications should import this package directly.

Installation

pnpm add @happyvertical/smrt-sales

Add svelte when consuming the optional UI export.

Modules

Entry pointResponsibility
@happyvertical/smrt-sales/agreementsVersioned commercial terms, verified e-signature execution, and immutable evidence
@happyvertical/smrt-sales/crmLeads, pipelines, opportunities, activities, conversions
@happyvertical/smrt-sales/referralsReferrers, links, attribution, qualification, agreements
@happyvertical/smrt-sales/commissionsEarners, plans, earning events, commissions, payouts
@happyvertical/smrt-sales/svelteCRM, referrer, commission, and operator surfaces

The root export re-exports all TypeScript modules for convenience.

Quick start: commission terms

import {
  CommissionPlanCollection,
  EarnerCollection,
} from '@happyvertical/smrt-sales/commissions';

const db = 'sales.db';
const earners = await EarnerCollection.create({ db });
const plans = await CommissionPlanCollection.create({ db });

const earner = await earners.create({
  tenantId: 'tenant-1',
  profileId: 'profile-42',
  displayName: 'North Region Partner',
  status: 'active',
  currency: 'CAD',
});

const plan = await plans.create({
  tenantId: 'tenant-1',
  planKey: 'referral-standard',
  name: 'Standard referral plan',
  currency: 'CAD',
});
plan.setComponents([
  {
    key: 'collected-revenue',
    trigger: 'collected_revenue',
    basis: 'gross',
    rate: 0.1,
    recurrence: { kind: 'one_time' },
  },
]);
plan.activate();
await plan.save();

console.log(earner.id, plan.getComponents());

All money fields use integer cents. Rates and probability-like values use decimals from 0 to 1; rounding occurs through the exported money helpers.

Waterfall plans

Version-two plans can carry ordered steps, an effectiveTo boundary, and a remainderSink. calculateWaterfall() is a pure, generic allocation service: hosts register recipient resolvers, then persist the returned trace as the replay evidence. Step keys must be nonempty strings; malformed persisted keys are rejected before allocation or activation. Replay snapshots copy recipient and sink values, including nested metadata, so later caller-input mutation cannot change the returned evidence. The trace freezes the resolved recipients, input facts, and application-fee offset. All amounts are integer minor units; each percentage rounds half away from zero and recipients plus the sink always equal gross.

An application fee already settled at checkout is modeled only as an offset to the configured recipient's payable allocation. It is never emitted as a second allocation or payable. Offset matching uses the entire recipient descriptor, including nested metadata; object key order does not change identity. The service does not initiate a payout or transfer.

The referral qualification and commission bridge remain component-based. Both qualification and explicit requalification refuse a resolved waterfall plan with unsupported_plan_engine, before writing a snapshot or changing the referral. This applies to pinned plans and latest-active plan amendments. Existing frozen v1 snapshots keep governing earnings. To recover, activate and bind compatible component terms, then retry qualification; use calculateWaterfall() directly for v2 allocations. Switching a plan key's engine does not migrate referrals.

Pool recipients

A step can share its amount across a pool of members, weighted by a metric such as deliveries, items published, or referrals sent. The step's recipient names the pool and resolves like any other recipient; the host injects who belongs to it and how much each member contributed:

import {
  calculateWaterfallWithPools,
  WaterfallRecipientResolverRegistry,
} from '@happyvertical/smrt-sales/commissions';

const resolver = new WaterfallRecipientResolverRegistry();
resolver.register('treasury', () => ({ kind: 'treasury', id: 'valley-coop' }));
resolver.register('grower_pool', (d) => ({ kind: 'grower_pool', id: d.id ?? 'all' }));

const { trace } = await calculateWaterfallWithPools(
  {
    planKey: 'valley-coop-wholesale',
    version: 1,
    currency: 'USD',
    steps: [
      { key: 'treasury', base: 'gross', amount: { kind: 'percent', rate: 0.1 },
        recipient: { kind: 'treasury' } },
      { key: 'growers', base: 'previous_remainder', amount: { kind: 'percent', rate: 1 },
        recipient: { kind: 'grower_pool', id: '2026-season' },
        pool: { metric: 'kg_delivered' } },
    ],
    remainderSink: { kind: 'treasury' },
  },
  { grossAmountCents: 10_000, currency: 'USD' },
  {
    resolver,
    poolMembers: async (pool) => loadGrowers(pool.id),
    metricProvider: { getMetricValues: async (req) => loadKgDelivered(req) },
    metricPeriod: { start: '2026-09-01', end: '2026-10-01' },
  },
);

Omit metric for equal shares. Weights are non-negative integers, and members the provider leaves out weigh zero. Shares are exact integer minor units. The cents that cannot be divided go to the remainder sink by default. With residual: 'largest_remainder', they go one at a time to the largest fractional remainders. Ties go to the larger weight, then to member kind and id order. An empty pool goes to the sink. So does a pool whose weights are all zero, unless the step sets zeroWeight: 'equal'. The trace freezes the members, weights, and metric period, so a replay with frozenInputs never calls the providers again. A snapshot must also match the step's declared metric. Replay trusts the frozen inputs it receives, so store them where they cannot be edited, such as an immutable calculation trace; a consistent edit to the stored evidence cannot be detected here. calculateWaterfall() stays synchronous; pass it pools from prepareWaterfallPools() when you need the two phases apart.

Organisation and treasury earners

Earner.kind is person (the default), organisation, or treasury. Organisation and treasury earners need no person Profile. Payout methods include stripe_connect and crypto; setPayoutDestination() stores the connected account id or the public receiving address, and an active earner using either method must have one. The package records where money should go and never calls a payment provider.

CommissionPayoutService.createPayoutBatch() captures the typed destination on CommissionPayout.payoutDestination. Executors and approval screens must read payout.getPayoutDestination() from the batch, never the current Earner. The batch's method and destination are immutable from its first save, including pending batches and failed batches reset for retry. Earner preference changes, idempotent replay and interrupted membership repair never refresh routing. Reject the batch through transitionPayoutForSource and create a new batch with a new idempotency key to use another destination. This also preserves the route that was reviewed before approval; no payment provider is called here.

Run the normal manifest migration before adopting the new field. Existing Stripe Connect/crypto batches without a recorded descriptor remain readable, but cannot be approved or advanced toward payment. Reject and recreate them; never backfill a historical route from today's Earner. Manual methods continue to use an empty descriptor. Unknown/malformed descriptors and extra fields (including credentials) are rejected.

Core model

  • Roles are separate from money. SalesRepresentative and Referrer are distinct roles; both point to one neutral Earner payout identity.
  • Terms are versioned rows. Activated commission plans, attribution policies, and referral agreements are amended with new versions.
  • Evidence is immutable. Earning events, executed agreements, referral touches, and adjustments are append-only or guarded after activation.
  • Retries are explicit. Stable dedupe/idempotency keys prevent duplicated earning, click, adjustment, agreement, and payout operations.
  • Writes use services where required. Payout transitions, adjustments, agreement execution, and attribution have service-owned invariants that raw generated CRUD must not bypass.

Referrer nominations

Register known aliases with ReferrerIdentifierCollection.register(). A host can record a matched nomination at intake using ReferralNominationResolver and later resolve it under the referral program's active policy. An ambiguous or unknown nomination opens an operator review with the original input and policy version. Run the normal manifest migration to add referrer_identifiers. See referral behavior for matching rules, replay, and tenant boundaries.

Lead intake and lifecycle

LeadWorkflowService is the tenant-safe, application-facing seam for generic intake, follow-up, qualification, stage movement, and opportunity closure. Construct it with the host database inside an active withTenant() context; the host supplies authorization, actor/profile ids, and view-model mapping.

import { LeadWorkflowService } from '@happyvertical/smrt-sales/crm';

const workflow = await LeadWorkflowService.create({ db });
await workflow.startWorking({ leadId, actorProfileId });
await workflow.scheduleNextAction({
  leadId,
  actorProfileId,
  summary: 'Call after product review',
  dueAt: new Date('2026-10-01T16:00:00Z'),
});

The service atomically records assignment and status audit events, human activities, scheduled next actions, and monotonic task completion. createLead() requires a name and email or phone, normalizes email, supports an optional host-authorized profileId, and supports active-lead deduplication and caller-supplied idempotency keys. A terminal duplicate is reported for the host to resolve explicitly. qualifyLead() delegates to LeadCollection.qualify() and returns the linked opportunity. moveOpportunityToStage() atomically moves an open Opportunity between nonterminal same-pipeline stages; exact retries add no audit. closeOpportunity() selects the pipeline's won/lost stage and optionally records a won conversion link. CRM never creates the downstream target. Money remains integer cents via expectedValueCents; actor attribution uses actorProfileId.

LeadCollection.listInbox() provides tenant-scoped filtering, sorting, counts, and pagination with batched owner/next-action reads. getLeadWorkState() includes the linked opportunity. Duplicate merging remains owned by LeadCollection.mergeLeads().

LeadCreateForm, LeadList, and LeadDetail from /svelte receive view data and callbacks. The host controls inbox filters and pagination, duplicate decisions, routes, authorization, and service invocation. Components never fetch data. See the CRM contract for retry and duplicate semantics and the Svelte contract for the component surfaces.

Agreement boundary

Agreement is a counterparty-agnostic, effective-dated terms record. Parties are ordered { kind, id } descriptors, so consumers can use tenant, earner, profile, organization, worker, or their own neutral kinds without importing a consumer domain. Versions are rows: createAmendment() creates a draft and activateAmendment() closes the predecessor at the successor's start. Effective intervals are half-open ([effectiveFrom, effectiveTo)), and activeFor() is an as-of query: it can return a superseded or terminated version that governed the supplied record date, never terms inferred from today's status. Ambiguous overlapping intervals fail closed. Activation rejects backdated or out-of-order amendments that would overlap existing history. Ending a draft cancels it without making it govern; closed intervals cannot be reopened. Party JSON is canonicalized before persistence, so property order does not change an agreement's identity. Tenant lookups fall back to global terms for each requested date when no tenant version governs that date. A tenant must explicitly create its initial version before using amendment helpers; global terms are never implicitly copied into a tenant amendment. Callers that calculate money must snapshot the returned version at their authoritative event; this model does not settle or allocate funds.

The execution portion of the agreements module accepts the provider-neutral @happyvertical/signatures contract plus an AssetRuntimeLike. Provider credentials remain in the injected SDK adapter and secret store. Executed agreements freeze the exact source, signed document, audit trail, hashes, and signer evidence; amendments create new records.

Tenancy and cross-package references

Most business models are optionally tenant scoped so intentional global operator rows remain possible. Execution evidence and private operation fences are required-tenant records. Profile, invoice, and asset references use cross-package string references rather than circular runtime dependencies.

Migration from affiliates

See smrt-affiliates and its migration guide for the legacy mapping: Partner becomes Earner, and Payout becomes CommissionPayout. The compatibility package owns no duplicate models or tables.

Development

pnpm --filter @happyvertical/smrt-sales test
pnpm --filter @happyvertical/smrt-sales typecheck
pnpm --filter @happyvertical/smrt-sales test:postgres
pnpm --filter @happyvertical/smrt-sales build

See AGENTS.md for lifecycle, evidence, concurrency, and payout invariants.

A future amendment activated through activateAmendment can be withdrawn through withdrawAmendment(id) only before its start, while it is still active. This transaction cancels the never-effective successor and restores its exact persisted predecessor end (including a finite end); it never infers an open-ended interval. Repeated, late, or conflicting withdrawals fail without changing history. Direct model termination remains for already-effective terms. Global defaults apply only before a tenant lane first governs; termination, expiry, and later gaps in that lane return no agreement instead of silently resuming global fees.

Restoration provenance is written exclusively by amendment activation; ordinary creates and saves cannot supply or edit it. Withdrawal advances both persisted revision tokens so pre-withdrawal model instances cannot overwrite the result.

Initial agreement creates use strict insertion: concurrent callers for the same tenant, kind, parties and version cannot replace the winning row or its terms. The losing create fails; load the existing version or create an amendment.

Concurrent createAmendment calls serialize version allocation within the owning lane: PostgreSQL locks the oldest persisted version and re-reads the latest; embedded engines use core's transaction/write queue. Each successful call keeps its own terms and version. Direct supersede() requires a finite effectiveTo set before the transition; saving an open-ended superseded row is rejected.

Governed sales are available from /crm: SalesGovernanceService authorizes sellers, exclusively leases canonical advertisers, freezes quote revisions and requires exact maker/checker discount approval. Hosts supply current membership, suspension, inventory and seller/finance policies. See the governed sales integration contract for transactional executor ownership, migration and provider signing boundaries. The Svelte export includes SellerGovernancePanel and its view/action contracts.

Governance currently accepts owned PostgreSQL connection configurations only. Other adapters fail before connection creation. Full issue #4264 remains blocked on SDK DuckDB connection visibility #1452.

SQLite governance is also refused before opening because same-process recovery from BUSY invalidation has not been proven for this workflow. Previous SQLite behavioral tests are investigation evidence, not a supported runtime claim. Follow-up validation is tracked in s-m-r-t #4269.

版本与发布记录

@happyvertical/smrt-sales 共发布 292 个版本,首次发布于 2026/07/11;过去 12 个月发布了 292 个版本。

版本发布日期距今
0.62.1latest2026/11/17今天
0.62.02026/11/17今天
0.61.62026/11/161 天前
0.61.52026/11/161 天前
0.61.42026/11/161 天前
0.61.32026/11/152 天前

关于 @happyvertical/smrt-sales 的常见问题

@happyvertical/smrt-sales 是什么?

Modular sales for the SMRT framework: agreement execution, CRM, referral intake, neutral commissions, and reusable Svelte surfaces

如何安装 @happyvertical/smrt-sales?

在项目目录运行 npm install @happyvertical/smrt-sales,或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖:svelte(^5.57.0)。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖,Yarn 需要手动安装。

@happyvertical/smrt-sales 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@happyvertical/smrt-sales 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@happyvertical/smrt-sales 可以商用吗?

@happyvertical/smrt-sales 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@happyvertical/smrt-sales 的下载量有多少?

根据 npm 官方下载统计,@happyvertical/smrt-sales 在 2026/10/17 – 2026/11/15 这 30 天内被下载 15,167 次,日均约 506 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@happyvertical/smrt-sales 还在维护吗?

最新版本 0.62.1 发布于 2026/11/17(今天);至今共发布 292 个版本,其中过去 12 个月发布了 292 个;首次发布于 2026/07/11。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。