@happyvertical/smrt-sales 0.55.6 → 0.55.8

package/dist/smrt-knowledge.json

@@ -3,12 +3,12 @@
   "sensitiveFieldsExcluded": true,
   "generatedAt": "1970-01-01T00:00:00.000Z",
   "packageName": "@happyvertical/smrt-sales",
-  "packageVersion": "0.55.6",
+  "packageVersion": "0.55.8",
   "sourceManifestPath": "dist/manifest.json",
   "agentDocPath": "AGENTS.md",
   "sourceHashes": {
-    "manifest": "e59e9b1e27dd561a2efefaedca00ffac5567632a3bfceacad7ebde9b7333d603",
-    "packageJson": "4c9205a730dd49cdb28b609454e8d3f8625b5973ce69b46f7b80ae523fbe5f23",
+    "manifest": "1887146936b7a4eb60c24a5b62240cc447fba429693c4330dd90683323e85362",
+    "packageJson": "90f6fd25c8e143e0a5f0ed202edb263576b8e59195a6a9b9c19a9a2abb7d78ec",
     "agents": "3100099d7cef116237e4deb4f83e32d836f3cc26e0f68a7dd55f14de942eda11",
     "moduleDoc:agents/agreements.md": "eb6ff147a0f60ee627d3337e8e9394d06fda955b4a4fff228537a9bd2803f886",
     "moduleDoc:agents/commissions.md": "e047024aafe5edcf072c1a6b7ea253c24cb15f2fa1beb2edd13651e735921f73",
@@ -3120,6 +3120,7 @@
       "name": "CommissionAdjustmentOperation",
       "qualifiedName": "@happyvertical/smrt-sales:CommissionAdjustmentOperation",
       "collection": "commissionadjustmentoperations",
+      "description": "One globally unique adjustment operation UUID mapped to its adjustment.",
       "tableName": "commission_adjustment_operations",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -5395,6 +5396,7 @@
       "qualifiedName": "@happyvertical/smrt-sales:Lead",
       "displayLabelField": "name",
       "collection": "leads",
+      "description": "Lead is an identified prospect: a person/organization that showed intent but has not yet been qualified into an Opportunity.",
       "tableName": "leads",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -5410,35 +5412,40 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What you call this lead."
         },
         {
           "name": "contactName",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The person to talk to."
         },
         {
           "name": "email",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Their email address."
         },
         {
           "name": "phone",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "Their phone number."
         },
         {
           "name": "organizationName",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The company they are with."
         },
         {
           "name": "profileId",
@@ -5452,14 +5459,16 @@
           "type": "foreignKey",
           "required": false,
           "related": "SalesRepresentative",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The sales representative who owns this lead."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "new"
+          "default": "new",
+          "description": "Where the lead stands, for example new or qualified."
         },
         {
           "name": "sourceKind",
@@ -5784,6 +5793,7 @@
       "qualifiedName": "@happyvertical/smrt-sales:Opportunity",
       "displayLabelField": "name",
       "collection": "opportunities",
+      "description": "Opportunity is a qualified engagement: a deal with an expected value moving through the stages of a PipelineDefinition.",
       "tableName": "opportunities",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -5799,69 +5809,79 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What you call this deal."
         },
         {
           "name": "leadId",
           "type": "foreignKey",
           "required": false,
           "related": "Lead",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The lead it came from."
         },
         {
           "name": "ownerRepId",
           "type": "foreignKey",
           "required": false,
           "related": "SalesRepresentative",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The sales representative who owns this deal."
         },
         {
           "name": "pipelineId",
           "type": "foreignKey",
           "required": false,
           "related": "PipelineDefinition",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The pipeline it moves through."
         },
         {
           "name": "stageId",
           "type": "foreignKey",
           "required": false,
           "related": "PipelineStage",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The stage it is at now."
         },
         {
           "name": "expectedValueCents",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "What you expect the deal to be worth, in cents."
         },
         {
           "name": "currency",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "USD"
+          "default": "USD",
+          "description": "The currency of that value."
         },
         {
           "name": "probability",
           "type": "decimal",
           "required": false,
           "columnType": "REAL",
-          "default": 0
+          "default": 0,
+          "description": "How likely it is to close, as a decimal (0.5 is 50%)."
         },
         {
           "name": "expectedCloseAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When you expect it to close."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "open"
+          "default": "open",
+          "description": "open, won or lost."
         },
         {
           "name": "outcomeReason",
@@ -6138,6 +6158,7 @@
       "name": "OpportunityConversion",
       "qualifiedName": "@happyvertical/smrt-sales:OpportunityConversion",
       "collection": "opportunityconversions",
+      "description": "OpportunityConversion records that a WON opportunity materialized into a downstream record — a client, project, contract, subscription, or any caller-defined kind.",
       "tableName": "opportunity_conversions",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -6299,6 +6320,7 @@
       "qualifiedName": "@happyvertical/smrt-sales:PipelineDefinition",
       "displayLabelField": "name",
       "collection": "pipelinedefinitions",
+      "description": "PipelineDefinition names an ordered set of stages that opportunities move through. Pipelines are configuration rows, not code: tenants can run several (e.g.",
       "tableName": "pipeline_definitions",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -6314,35 +6336,40 @@
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short code for the pipeline."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the pipeline is called."
         },
         {
           "name": "isDefault",
           "type": "boolean",
           "required": false,
           "columnType": "BOOLEAN",
-          "default": false
+          "default": false,
+          "description": "Whether this is the default pipeline for new deals."
         },
         {
           "name": "status",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "active"
+          "default": "active",
+          "description": "Whether the pipeline is active (accepts new deals) or archived."
         },
         {
           "name": "metadata",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "{}"
+          "default": "{}",
+          "description": "Extra details kept with the pipeline."
         }
       ],
       "relationships": [],
@@ -6505,6 +6532,7 @@
       "qualifiedName": "@happyvertical/smrt-sales:PipelineStage",
       "displayLabelField": "name",
       "collection": "pipelinestages",
+      "description": "PipelineStage is a configurable step within a pipeline.",
       "tableName": "pipeline_stages",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -6520,49 +6548,56 @@
           "type": "foreignKey",
           "required": true,
           "related": "PipelineDefinition",
-          "columnType": "UUID"
+          "columnType": "UUID",
+          "description": "The pipeline this stage belongs to."
         },
         {
           "name": "key",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "A short code for the stage."
         },
         {
           "name": "name",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What the stage is called."
         },
         {
           "name": "sortOrder",
           "type": "integer",
           "required": false,
           "columnType": "INTEGER",
-          "default": 0
+          "default": 0,
+          "description": "Where it comes in the pipeline."
         },
         {
           "name": "probability",
           "type": "decimal",
           "required": false,
           "columnType": "REAL",
-          "default": 0
+          "default": 0,
+          "description": "How likely a deal at this stage is to close, as a decimal."
         },
         {
           "name": "isWon",
           "type": "boolean",
           "required": false,
           "columnType": "BOOLEAN",
-          "default": false
+          "default": false,
+          "description": "Whether reaching this stage closes the deal as won."
         },
         {
           "name": "isLost",
           "type": "boolean",
           "required": false,
           "columnType": "BOOLEAN",
-          "default": false
+          "default": false,
+          "description": "Whether reaching this stage closes the deal as lost."
         },
         {
           "name": "metadata",
@@ -6692,6 +6727,7 @@
       "name": "SalesActivity",
       "qualifiedName": "@happyvertical/smrt-sales:SalesActivity",
       "collection": "salesactivities",
+      "description": "SalesActivity is the shared trail for Leads and Opportunities: human touchpoints (note, call, email, meeting), next actions (task with dueAt/completedAt), and framework-written audit rows…",
       "tableName": "sales_activities",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -6707,40 +6743,46 @@
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "lead"
+          "default": "lead",
+          "description": "What the activity is about: a lead or an opportunity."
         },
         {
           "name": "subjectId",
           "type": "text",
           "required": true,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "The lead or opportunity it is about."
         },
         {
           "name": "activityKind",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": "note"
+          "default": "note",
+          "description": "The kind of activity, for example call, note or email."
         },
         {
           "name": "summary",
           "type": "text",
           "required": false,
           "columnType": "TEXT",
-          "default": ""
+          "default": "",
+          "description": "What happened or what needs doing."
         },
         {
           "name": "dueAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When it is due."
         },
         {
           "name": "completedAt",
           "type": "datetime",
           "required": false,
-          "columnType": "TIMESTAMP"
+          "columnType": "TIMESTAMP",
+          "description": "When it was done."
         },
         {
           "name": "actorProfileId",
@@ -6884,6 +6926,7 @@
       "qualifiedName": "@happyvertical/smrt-sales:SalesRepresentative",
       "displayLabelField": "title",
       "collection": "salesrepresentatives",
+      "description": "SalesRepresentative is a ROLE model: it links an identity (smrt-profiles Profile) to sales ownership (Leads/Opportunities reference ownerRepId).",
       "tableName": "sales_representatives",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -9771,6 +9814,7 @@
       "name": "ReferralClickOperation",
       "qualifiedName": "@happyvertical/smrt-sales:ReferralClickOperation",
       "collection": "referralclickoperations",
+      "description": "One globally unique caller replay key mapped to its immutable click touch.",
       "tableName": "referral_click_operations",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -9866,6 +9910,7 @@
       "qualifiedName": "@happyvertical/smrt-sales:ReferralLink",
       "displayLabelField": "label",
       "collection": "referrallinks",
+      "description": "A ReferralLink is the shareable artifact a Referrer distributes: a globally unique code (natural key ['code'] — codes resolve without knowing the tenant/program) plus an optional destination…",
       "tableName": "referral_links",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -10127,6 +10172,7 @@
       "qualifiedName": "@happyvertical/smrt-sales:ReferralProgram",
       "displayLabelField": "name",
       "collection": "referralprograms",
+      "description": "A ReferralProgram anchors links, touches, referrals, agreements, and exceptions, and carries the program-level DEFAULTS:",
       "tableName": "referral_programs",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -10786,6 +10832,7 @@
       "name": "Referrer",
       "qualifiedName": "@happyvertical/smrt-sales:Referrer",
       "collection": "referrers",
+      "description": "Referrer is a ROLE model: it links an identity (smrt-profiles Profile) to referral activity (ReferralLinks, ReferralTouches, and Referrals reference referrerId).",
       "tableName": "referrers",
       "packageName": "@happyvertical/smrt-sales",
       "extends": "SmrtObject",
@@ -14392,5 +14439,153 @@
       "module": "svelte",
       "content": "# smrt-sales/svelte\n\nPer-module semantics for `@happyvertical/smrt-sales/svelte`. Package orientation, the\ncross-module invariants (currency, tenancy, cross-package refs, roles vs.\nmoney), and the Gotchas that apply before editing anything live in\n[../AGENTS.md](../AGENTS.md) — read that first.\n\nProps-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`.\n\n`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.\n"
     }
-  ]
+  ],
+  "recipes": [
+    {
+      "id": "sales.pipeline",
+      "className": "SalesPipelineRecipe",
+      "label": "Leads & pipeline",
+      "summary": "Capture leads and move them through your sales stages.",
+      "synonyms": [
+        "crm",
+        "prospects",
+        "opportunities",
+        "deals",
+        "funnel"
+      ],
+      "models": [
+        "@happyvertical/smrt-sales:Lead",
+        "@happyvertical/smrt-sales:Opportunity",
+        "@happyvertical/smrt-sales:PipelineDefinition",
+        "@happyvertical/smrt-sales:PipelineStage",
+        "@happyvertical/smrt-sales:SalesActivity"
+      ],
+      "nav": [
+        {
+          "label": "Leads",
+          "model": "@happyvertical/smrt-sales:Lead",
+          "icon": "users",
+          "description": "People who might become customers, and where each one stands."
+        },
+        {
+          "label": "Opportunities",
+          "model": "@happyvertical/smrt-sales:Opportunity",
+          "icon": "briefcase",
+          "description": "Deals in progress, with their value and next step."
+        },
+        {
+          "label": "Pipelines",
+          "model": "@happyvertical/smrt-sales:PipelineDefinition",
+          "icon": "layers",
+          "description": "The stages a deal moves through on its way to a sale."
+        }
+      ],
+      "requires": [],
+      "section": {
+        "id": "sales",
+        "label": "Sales",
+        "icon": "shoppingBag",
+        "description": "Customers, orders and quotes: everything you sell."
+      },
+      "options": {
+        "@happyvertical/smrt-sales:Lead": {
+          "fields": {
+            "profileId": {
+              "visibility": "hidden"
+            },
+            "mergedIntoId": {
+              "visibility": "hidden"
+            },
+            "sourceKind": {
+              "visibility": "hidden"
+            },
+            "sourceId": {
+              "visibility": "hidden"
+            },
+            "acquisitionContext": {
+              "visibility": "hidden"
+            },
+            "intakeRef": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            },
+            "qualifiedAt": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:Opportunity": {
+          "fields": {
+            "sourceKind": {
+              "visibility": "hidden"
+            },
+            "sourceId": {
+              "visibility": "hidden"
+            },
+            "metadata": {
+              "visibility": "hidden"
+            },
+            "outcomeReason": {
+              "visibility": "hidden"
+            },
+            "wonAt": {
+              "visibility": "hidden"
+            },
+            "lostAt": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:PipelineStage": {
+          "fields": {
+            "metadata": {
+              "visibility": "hidden"
+            }
+          }
+        },
+        "@happyvertical/smrt-sales:SalesActivity": {
+          "fields": {
+            "metadata": {
+              "visibility": "hidden"
+            },
+            "actorProfileId": {
+              "visibility": "hidden"
+            }
+          }
+        }
+      },
+      "help": {
+        "markdown": "## Overview\n\nLeads and pipeline is a light CRM. You capture leads, turn the promising ones\ninto opportunities, and move each through the stages of a pipeline. Activities\nrecord calls, notes and follow-ups.\n\n## Tasks\n\n### Capture a lead\n\n1. Create a new lead.\n2. Enter the **{field:name}**, **{field:email}** and **{field:phone}**.\n3. Keep **{field:status}** up to date as you qualify them.\n\n### Work an opportunity\n\n1. Create a pipeline, then add its stages in order.\n2. Create a new opportunity and pick the **{field:leadId}**.\n3. Choose the **{field:pipelineId}** and **{field:stageId}**, and enter the\n   **{field:expectedValueCents}** and **{field:expectedCloseAt}**.\n4. Move the **{field:stageId}** along as the deal progresses.\n",
+        "fieldRefs": [
+          "email",
+          "expectedCloseAt",
+          "expectedValueCents",
+          "leadId",
+          "name",
+          "phone",
+          "pipelineId",
+          "stageId",
+          "status"
+        ]
+      },
+      "demo": {
+        "mode": "server",
+        "reasons": [
+          "Needs a server because its package does not build for a browser: node:crypto; and its package depends on @happyvertical/smrt-tenancy, which do not build for a browser (#3624)."
+        ]
+      }
+    }
+  ],
+  "browser": {
+    "status": "server-only",
+    "issues": [
+      "#3624"
+    ],
+    "reason": "node:crypto",
+    "via": [
+      "@happyvertical/smrt-tenancy"
+    ]
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-sales",
-  "version": "0.55.6",
+  "version": "0.55.8",
   "smrtJsdoc": "strict",
   "description": "Modular sales for the SMRT framework: agreement execution, CRM, referral intake, neutral commissions, and reusable Svelte surfaces",
   "type": "module",
@@ -42,18 +42,18 @@
     "./manifest.json": "./dist/manifest.json"
   },
   "dependencies": {
-    "@happyvertical/signatures": "^0.102.4",
-    "@happyvertical/smrt-assets": "0.55.6",
-    "@happyvertical/smrt-core": "0.55.6",
-    "@happyvertical/smrt-tenancy": "0.55.6",
-    "@happyvertical/smrt-ui": "0.55.6",
-    "@happyvertical/sql": "^0.102.4"
+    "@happyvertical/signatures": "^0.103.1",
+    "@happyvertical/smrt-assets": "0.55.8",
+    "@happyvertical/smrt-core": "0.55.8",
+    "@happyvertical/smrt-tenancy": "0.55.8",
+    "@happyvertical/smrt-ui": "0.55.8",
+    "@happyvertical/sql": "^0.103.1"
   },
   "peerDependencies": {
     "svelte": "^5.57.0"
   },
   "devDependencies": {
-    "@happyvertical/smrt-vitest": "0.55.6",
+    "@happyvertical/smrt-vitest": "0.55.8",
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.3.0",
     "@types/node": "24.13.6",