@happyvertical/smrt-sales 0.54.2 → 0.54.4

package/AGENTS.md

@@ -61,8 +61,8 @@ Business/domain models are generally `@TenantScoped({ mode: 'optional' })` with
 - **Manifest objects must remain root-importable**: generated consumer registration imports every manifest-advertised model and collection from `@happyvertical/smrt-sales`. The `CommissionAdjustmentOperation` and `ReferralClickOperation` model/collection values are therefore root and owning-subpath exports for runtime loading, while their `api: false`, `mcp: false`, and `cli: false` decorators keep them off generated application surfaces. Publish-pack validation imports the actual CLI-generated register against the packed tarball.
 - **CommissionPayout, not Payout**: avoids the pre-existing global table-name collision between commerce `Payout` and legacy affiliates `Payout` (`payouts`).
 - **Table names are global**: new models were named to avoid collisions across packages (`commission_payouts`, `sales_activities`, `attribution_policies`, …).
-- **Svelte module is svelte-check-gated**: no runtime component tests; `typecheck` runs `svelte-check` via `scripts/svelte-check-a11y.mjs`. Ship raw `.svelte` via `svelte-package`.
-- **Lead follow-up stays generic**: call `LeadWorkflowService` for audited Lead assignment/status/activity/task mutations under ambient tenancy; it locks rows, rejects cross-tenant identifiers, and has no authorization, SLA, automatic-owner, reminder, website-contact, or conversion policy. `LeadDetail` is props/callback only; host applications map state and call the service.
+- **Svelte validation includes interaction contracts**: intake and inbox components have runtime component tests; `typecheck` also runs `svelte-check` via `scripts/svelte-check-a11y.mjs`. Ship raw `.svelte` via `svelte-package`.
+- **Lead workflows stay generic**: call `LeadWorkflowService` for tenant-safe intake, audited follow-up, qualification, and opportunity closure with optional conversion links. The service delegates CRM lifecycles to their owning collections; hosts supply authorization and create downstream records. `LeadCreateForm`, `LeadList`, and `LeadDetail` are props/callback only. See [agents/crm.md](agents/crm.md) for dedupe, retry, and inbox contracts.
 - **Model transition methods don't save**: `markEarned()/approve()/markPayable()/markPaid()` (Commission) and the payout transitions mutate + stamp timestamps only — callers save; the settlement/payout services do both.
 - **`reject()` alone strands rows**: the model method only flips status — always reject through `transitionPayoutForSource`, which releases the batch's membership in the same transaction; stamped rows on a rejected payout would be unsettleable forever.
 - **The payout source stamp is derived data, never authorization**: `sourceKind`/`sourceId` on CommissionPayout index the history listing; both the listing and the lifecycle service re-verify actual membership and fail closed when the stamp cannot be proven.

package/README.md

@@ -86,10 +86,10 @@ decimals from `0` to `1`; rounding occurs through the exported money helpers.
   agreement execution, and attribution have service-owned invariants that raw
   generated CRUD must not bypass.
 
-## Lead follow-up workflow
+## Lead intake and lifecycle
 
 `LeadWorkflowService` is the tenant-safe, application-facing seam for generic
-pre-qualification follow-up. Construct it with the host database inside an
+intake, follow-up, qualification, 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.
 
@@ -107,11 +107,25 @@ await workflow.scheduleNextAction({
 ```
 
 The service atomically records assignment and status audit events, human
-activities, scheduled next actions, and monotonic task completion. Qualification
-and duplicate merge ownership remain respectively with `LeadCollection.qualify()`
-and `LeadCollection.mergeLeads()`. `LeadDetail` from the `/svelte` subpath is
-props- and callback-driven; it never fetches data or applies authorization/SLA
-policy.
+activities, scheduled next actions, and monotonic task completion.
+`createLead()` requires a name and email or phone, normalizes email, 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; `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](agents/crm.md) for retry and duplicate semantics and
+[the Svelte contract](agents/svelte.md) for the component surfaces.
 
 ## Agreement boundary
 

package/agents/crm.md

@@ -10,7 +10,46 @@ money), and the Gotchas that apply before editing anything live in
 - **PipelineDefinition / PipelineStage**: configurable ordered stages with default `new → qualified → discovery → proposal → negotiation → closed_won | closed_lost` (seeded via `ensureDefaultPipeline()`); stages carry `probability` and `isWon`/`isLost` terminal flags.
 - **Opportunity**: qualified engagement — owner, pipeline + stage, `expectedValueCents`, `probability`, `expectedCloseAt`, outcome. Stage movement validated against the pipeline; terminal stages set `won|lost` status.
 - **SalesActivity**: activity/next-action trail for Leads and Opportunities (`subjectKind`/`subjectId`), also the audit trail for assignment, qualification, merges, and stage movement.
-- **LeadWorkflowService**: the required tenant-safe pre-qualification mutation seam. It transactionally locks the Lead (and completion task on PostgreSQL), accepts only active same-tenant representatives, writes assignment/status/completion audits alongside their mutations, and returns merge-aware timeline/work-state reads. It owns `new | disqualified → working`, `new | working → disqualified`, human follow-up (`note | call | email | meeting`), and task scheduling/completion; qualification and merging remain collection lifecycles.
+- **LeadWorkflowService**: the required tenant-safe Lead mutation seam. It transactionally locks the affected Lead/Opportunity (and completion task on PostgreSQL), accepts only active same-tenant representatives, writes actor-attributed audits alongside mutations, and returns merge-aware timeline/work-state reads. It owns validated `createLead()` intake, `new | disqualified → working`, `new | working → disqualified`, human follow-up (`note | call | email | meeting`), task scheduling/completion, delegated qualification, and terminal Opportunity closure/conversion. Merging remains a collection lifecycle.
 - **OpportunityConversion**: idempotent conversion links (`targetKind`/`targetId` — client, project, contract, subscription, …) with a composite natural key. CRM never creates downstream records itself and never mutates referral or commission state.
 
-Workflow calls require ambient tenant context and an actor profile id. Fail closed for foreign/missing Lead, representative, and task ids without revealing their existence. Human metadata is plain JSON-object data; framework audit metadata is generated separately. Keep queue projection pure (`now`/optional timezone are injected) and do not add assignment, reminder, SLA, authorization, or conversion policy.
+Workflow calls require ambient tenant context. Mutations require an actor profile
+id except `createLead()`, whose actor is optional for automated intake. Fail
+closed for foreign/missing Lead, Opportunity, pipeline, representative, and task
+ids without revealing their existence. Human metadata is plain JSON-object data;
+framework audit metadata is generated separately. Keep queue projection pure
+(`now`/optional timezone are injected) and do not add assignment, reminder, SLA,
+authorization, or conversion policy.
+
+`createLead()` requires a name and at least one of email/phone, normalizes email,
+and supports `none | email | email_or_org` tenant-local dedupe. Active duplicates
+return the existing Lead and append one `inbound` activity per novel normalized
+intent; terminal matches return `{ created: false, duplicateOf }` without mutation
+so the caller must explicitly retry with `dedupe: 'none'` to create another Lead.
+Caller idempotency keys are persisted through deterministic immutable activity
+ids, including when intake resolves to an existing active Lead; reusing a key
+with changed intent is rejected. PostgreSQL uses transaction advisory/row locks,
+while single-connection adapters serialize the entire transaction.
+
+`qualifyLead()` delegates to `LeadCollection.qualify()` on the same transaction
+executor and returns whether the Opportunity was newly created. `closeOpportunity()`
+resolves the configured won/lost terminal stage, delegates stage movement, and
+optionally records a won conversion in the same transaction. Exact retries add
+no stage activity or conversion. `getLeadWorkState()` includes the canonical
+linked Opportunity when present. Transaction-bound result models are reloaded
+on the service database after commit before being returned.
+
+`LeadCollection.listInbox({ status?, ownerRepId?, unassigned?, overdue?,
+search?, sort?, limit, offset, now? })` requires ambient tenancy and returns
+`{ leads, items, total, statusCounts }`. `leads` are hydrated Lead rows; aligned
+`items` add the hydrated owner and earliest open Lead task as `nextAction`
+without per-row queries. Search trims and performs case-insensitive literal
+substring matching across name, contact name, email, phone, and organization.
+Sort values are `created | next_action | name`, all with stable id tie-breaks;
+missing next actions sort last. `limit` is required from 1–100 and `offset` is
+required and nonnegative.
+
+`total` applies every selected filter. `statusCounts` contains `all`, every Lead
+status, `unassigned`, and `overdue`; counts retain owner/search scope but ignore
+the selected status/unassigned/overdue tab. Overdue means the earliest open task
+is due strictly before injected `now` (default current time).

package/agents/svelte.md

@@ -5,6 +5,6 @@ cross-module invariants (currency, tenancy, cross-package refs, roles vs.
 money), and the Gotchas that apply before editing anything live in
 [../AGENTS.md](../AGENTS.md) — read that first.
 
-Props-driven presentational components (no data fetching, no model-class imports, Provider-free smrt-ui primitives, `--smrt-*` tokens only): CRM — `SalesDashboard`, `LeadList`, `LeadDetail`, `OpportunityBoard`, `OpportunityDetail`; referrer portal — `ReferralLinkManager`, `ReferralStatusList`, `ReferrerEarningsSummary`, `CommissionBreakdown` (trace-explained amounts), `PayoutHistoryList`, `ExecutedAgreementsList`; operator — `AttributionConflictQueue` (award editor + required resolution reason), `PayoutBatchReview`, `CommissionExpenseSummary` (explicitly distinct from client invoices). Monetary props stay integer cents; `format.ts` converts at render. View-model prop types are exported interfaces (never inline intersected generics in `$props()`); pure helpers (dashboard math, Lead workflow action gating, award validation mirroring the service, payout action gating) are unit-tested while components are svelte-check-gated.
+Props-driven presentational components (no data fetching, no model-class imports, Provider-free smrt-ui primitives, `--smrt-*` tokens only): CRM — `SalesDashboard`, `LeadCreateForm`, `LeadList`, `LeadDetail`, `OpportunityBoard`, `OpportunityDetail`; referrer portal — `ReferralLinkManager`, `ReferralStatusList`, `ReferrerEarningsSummary`, `CommissionBreakdown` (trace-explained amounts), `PayoutHistoryList`, `ExecutedAgreementsList`; operator — `AttributionConflictQueue` (award editor + required resolution reason), `PayoutBatchReview`, `CommissionExpenseSummary` (explicitly distinct from client invoices). Monetary props stay integer cents; `format.ts` converts at render. View-model prop types are exported interfaces (never inline intersected generics in `$props()`). Pure helpers are unit-tested and Lead intake/inbox/detail components have mounted runtime tests through `vitest.ui.config.ts`.
 
-`LeadDetail` renders a complete host-supplied timeline and callback-only assignment, start/reopen, disqualification, human-activity, next-action, completion, and optional qualification controls. Its `busy` prop disables every mutation affordance; the host owns tenancy, authorization, service invocation, refresh, and any policy around due dates or reminders.
+`LeadCreateForm` validates the required name and email-or-phone contact rule, normalizes email, and emits a host-mapped `LeadCreateDraft`; source choices, duplicate results, errors, and owner choices come from the host. `LeadList` accepts controlled filter/count, sort, page, selection/link, and row-action props; the host owns inbox fetching and callback mutations. `LeadDetail` renders a complete host-supplied timeline, an optional linked-opportunity summary snippet, and callback-only assignment, start/reopen, disqualification, human-activity, next-action, completion, and qualification controls. Its `busy` prop disables every mutation affordance; the host owns tenancy, authorization, service invocation, refresh, and any policy around due dates or reminders.

package/dist/agreements.js

@@ -1,3 +1,3 @@
-import "./chunks/__smrt-register__-RRPKjeCe.js";
-import { a as AgreementExecutionEvent, c as AGREEMENT_EXECUTION_STATUSES, d as sanitizeSignerIntent, i as AgreementExecutionEventCollection, l as coerceAgreementDate, n as ExecutedAgreementCollection, o as AgreementExecutionCollection, r as ExecutedAgreement, s as AgreementExecution, t as AgreementExecutionService, u as sanitizeSignerEvidence } from "./chunks/agreements-CxHyIbZB.js";
+import "./chunks/__smrt-register__-Cxp00I21.js";
+import { a as AgreementExecutionEvent, c as AGREEMENT_EXECUTION_STATUSES, d as sanitizeSignerIntent, i as AgreementExecutionEventCollection, l as coerceAgreementDate, n as ExecutedAgreementCollection, o as AgreementExecutionCollection, r as ExecutedAgreement, s as AgreementExecution, t as AgreementExecutionService, u as sanitizeSignerEvidence } from "./chunks/agreements-BB_tNU0U.js";
 export { AGREEMENT_EXECUTION_STATUSES, AgreementExecution, AgreementExecutionCollection, AgreementExecutionEvent, AgreementExecutionEventCollection, AgreementExecutionService, ExecutedAgreement, ExecutedAgreementCollection, coerceAgreementDate, sanitizeSignerEvidence, sanitizeSignerIntent };