@happyvertical/smrt-sales 0.40.70 → 0.42.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AGENTS.md +1 -1
- package/dist/agreements.js +1 -1
- package/dist/chunks/__smrt-register__-AYT-m9Kw.js +6 -0
- package/dist/chunks/{__smrt-register__-BT2oZjFY.js.map → __smrt-register__-AYT-m9Kw.js.map} +1 -1
- package/dist/commissions.js +1 -1
- package/dist/crm.js +1 -1
- package/dist/index.js +1 -1
- package/dist/manifest.json +1937 -1570
- package/dist/referrals.js +1 -1
- package/dist/smrt-knowledge.json +386 -321
- package/package.json +6 -6
- package/dist/chunks/__smrt-register__-BT2oZjFY.js +0 -6
package/dist/smrt-knowledge.json
CHANGED
|
@@ -3,13 +3,13 @@
|
|
|
3
3
|
"sensitiveFieldsExcluded": true,
|
|
4
4
|
"generatedAt": "1970-01-01T00:00:00.000Z",
|
|
5
5
|
"packageName": "@happyvertical/smrt-sales",
|
|
6
|
-
"packageVersion": "0.
|
|
6
|
+
"packageVersion": "0.42.0",
|
|
7
7
|
"sourceManifestPath": "dist/manifest.json",
|
|
8
8
|
"agentDocPath": "AGENTS.md",
|
|
9
9
|
"sourceHashes": {
|
|
10
|
-
"manifest": "
|
|
11
|
-
"packageJson": "
|
|
12
|
-
"agents": "
|
|
10
|
+
"manifest": "6661f40aa9e1991b965dc58c578c242f1c2ff99a9e8fb7107c687877334b890f",
|
|
11
|
+
"packageJson": "fb2e9e801ffbfaa727c491f3686b87d17c2caf267eba53d28cf206d75a5b57e0",
|
|
12
|
+
"agents": "8731bdb94c727a97b289ebd88d0d0abfc1eba249aa8dd5ddd6b89ee3c92e1ca2",
|
|
13
13
|
"moduleDoc:agents/agreements.md": "eb6ff147a0f60ee627d3337e8e9394d06fda955b4a4fff228537a9bd2803f886",
|
|
14
14
|
"moduleDoc:agents/commissions.md": "e047024aafe5edcf072c1a6b7ea253c24cb15f2fa1beb2edd13651e735921f73",
|
|
15
15
|
"moduleDoc:agents/crm.md": "e90f813e857782bbfbd4122c9f67b61914e3ef49284a58e976a5507391851b0c",
|
|
@@ -56,6 +56,243 @@
|
|
|
56
56
|
"tags": [],
|
|
57
57
|
"risks": [],
|
|
58
58
|
"objects": [
|
|
59
|
+
{
|
|
60
|
+
"name": "AgreementExecutionCollection",
|
|
61
|
+
"qualifiedName": "@happyvertical/smrt-sales:AgreementExecutionCollection",
|
|
62
|
+
"collection": "agreementexecutions",
|
|
63
|
+
"tableName": "agreement_execution_collections",
|
|
64
|
+
"packageName": "@happyvertical/smrt-sales",
|
|
65
|
+
"extends": "SmrtCollection",
|
|
66
|
+
"fields": [],
|
|
67
|
+
"relationships": [],
|
|
68
|
+
"methods": [
|
|
69
|
+
"bindEvidenceArtifact",
|
|
70
|
+
"bindProviderRequest",
|
|
71
|
+
"claimCreateAttempt",
|
|
72
|
+
"compareAndSetLifecycle",
|
|
73
|
+
"completeCreateAttempt",
|
|
74
|
+
"failCreateAttempt",
|
|
75
|
+
"findByIdempotencyKey",
|
|
76
|
+
"findByProviderRequest",
|
|
77
|
+
"findBySource",
|
|
78
|
+
"incrementAttemptCount",
|
|
79
|
+
"updateLastError"
|
|
80
|
+
],
|
|
81
|
+
"methodSignatures": [
|
|
82
|
+
{
|
|
83
|
+
"name": "bindEvidenceArtifact",
|
|
84
|
+
"async": true,
|
|
85
|
+
"params": [
|
|
86
|
+
"input: BindAgreementEvidenceArtifactInput"
|
|
87
|
+
],
|
|
88
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
89
|
+
},
|
|
90
|
+
{
|
|
91
|
+
"name": "bindProviderRequest",
|
|
92
|
+
"async": true,
|
|
93
|
+
"params": [
|
|
94
|
+
"input: BindAgreementProviderRequestInput"
|
|
95
|
+
],
|
|
96
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
97
|
+
},
|
|
98
|
+
{
|
|
99
|
+
"name": "claimCreateAttempt",
|
|
100
|
+
"async": true,
|
|
101
|
+
"params": [
|
|
102
|
+
"input: ClaimAgreementCreateAttemptInput"
|
|
103
|
+
],
|
|
104
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
105
|
+
},
|
|
106
|
+
{
|
|
107
|
+
"name": "compareAndSetLifecycle",
|
|
108
|
+
"async": true,
|
|
109
|
+
"params": [
|
|
110
|
+
"input: CompareAndSetAgreementLifecycleInput"
|
|
111
|
+
],
|
|
112
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
113
|
+
},
|
|
114
|
+
{
|
|
115
|
+
"name": "completeCreateAttempt",
|
|
116
|
+
"async": true,
|
|
117
|
+
"params": [
|
|
118
|
+
"input: CompleteAgreementCreateAttemptInput"
|
|
119
|
+
],
|
|
120
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
121
|
+
},
|
|
122
|
+
{
|
|
123
|
+
"name": "failCreateAttempt",
|
|
124
|
+
"async": true,
|
|
125
|
+
"params": [
|
|
126
|
+
"input: FailAgreementCreateAttemptInput"
|
|
127
|
+
],
|
|
128
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
129
|
+
},
|
|
130
|
+
{
|
|
131
|
+
"name": "findByIdempotencyKey",
|
|
132
|
+
"async": true,
|
|
133
|
+
"params": [
|
|
134
|
+
"idempotencyKey: string"
|
|
135
|
+
],
|
|
136
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
137
|
+
},
|
|
138
|
+
{
|
|
139
|
+
"name": "findByProviderRequest",
|
|
140
|
+
"async": true,
|
|
141
|
+
"params": [
|
|
142
|
+
"provider: string",
|
|
143
|
+
"providerRequestId: string"
|
|
144
|
+
],
|
|
145
|
+
"returns": "Promise<AgreementExecution | null>"
|
|
146
|
+
},
|
|
147
|
+
{
|
|
148
|
+
"name": "findBySource",
|
|
149
|
+
"async": true,
|
|
150
|
+
"params": [
|
|
151
|
+
"sourceKind: string",
|
|
152
|
+
"sourceId: string"
|
|
153
|
+
],
|
|
154
|
+
"returns": "Promise<AgreementExecution[]>"
|
|
155
|
+
},
|
|
156
|
+
{
|
|
157
|
+
"name": "incrementAttemptCount",
|
|
158
|
+
"async": true,
|
|
159
|
+
"params": [
|
|
160
|
+
"tenantId: string",
|
|
161
|
+
"executionId: string"
|
|
162
|
+
],
|
|
163
|
+
"returns": "Promise<AgreementExecution>"
|
|
164
|
+
},
|
|
165
|
+
{
|
|
166
|
+
"name": "updateLastError",
|
|
167
|
+
"async": true,
|
|
168
|
+
"params": [
|
|
169
|
+
"input: UpdateAgreementExecutionErrorInput"
|
|
170
|
+
],
|
|
171
|
+
"returns": "Promise<AgreementExecution>"
|
|
172
|
+
}
|
|
173
|
+
],
|
|
174
|
+
"surfaces": [],
|
|
175
|
+
"relationshipFeatures": [
|
|
176
|
+
"uuidColumns"
|
|
177
|
+
],
|
|
178
|
+
"tags": [],
|
|
179
|
+
"risks": []
|
|
180
|
+
},
|
|
181
|
+
{
|
|
182
|
+
"name": "AgreementExecutionEventCollection",
|
|
183
|
+
"qualifiedName": "@happyvertical/smrt-sales:AgreementExecutionEventCollection",
|
|
184
|
+
"collection": "agreementexecutionevents",
|
|
185
|
+
"tableName": "agreement_execution_event_collections",
|
|
186
|
+
"packageName": "@happyvertical/smrt-sales",
|
|
187
|
+
"extends": "SmrtCollection",
|
|
188
|
+
"fields": [],
|
|
189
|
+
"relationships": [],
|
|
190
|
+
"methods": [
|
|
191
|
+
"findByDedupeKey",
|
|
192
|
+
"findByExecution",
|
|
193
|
+
"findProviderEventsByExecution",
|
|
194
|
+
"recordVerified"
|
|
195
|
+
],
|
|
196
|
+
"methodSignatures": [
|
|
197
|
+
{
|
|
198
|
+
"name": "findByDedupeKey",
|
|
199
|
+
"async": true,
|
|
200
|
+
"params": [
|
|
201
|
+
"dedupeKey: string"
|
|
202
|
+
],
|
|
203
|
+
"returns": "Promise<AgreementExecutionEvent | null>"
|
|
204
|
+
},
|
|
205
|
+
{
|
|
206
|
+
"name": "findByExecution",
|
|
207
|
+
"async": true,
|
|
208
|
+
"params": [
|
|
209
|
+
"executionId: string"
|
|
210
|
+
],
|
|
211
|
+
"returns": "Promise<AgreementExecutionEvent[]>"
|
|
212
|
+
},
|
|
213
|
+
{
|
|
214
|
+
"name": "findProviderEventsByExecution",
|
|
215
|
+
"async": true,
|
|
216
|
+
"params": [
|
|
217
|
+
"executionId: string"
|
|
218
|
+
],
|
|
219
|
+
"returns": "Promise<AgreementExecutionEvent[]>"
|
|
220
|
+
},
|
|
221
|
+
{
|
|
222
|
+
"name": "recordVerified",
|
|
223
|
+
"async": true,
|
|
224
|
+
"params": [
|
|
225
|
+
"options: VerifiedAgreementExecutionEventOptions"
|
|
226
|
+
],
|
|
227
|
+
"returns": "Promise<object>"
|
|
228
|
+
}
|
|
229
|
+
],
|
|
230
|
+
"surfaces": [],
|
|
231
|
+
"relationshipFeatures": [
|
|
232
|
+
"uuidColumns"
|
|
233
|
+
],
|
|
234
|
+
"tags": [],
|
|
235
|
+
"risks": []
|
|
236
|
+
},
|
|
237
|
+
{
|
|
238
|
+
"name": "ExecutedAgreementCollection",
|
|
239
|
+
"qualifiedName": "@happyvertical/smrt-sales:ExecutedAgreementCollection",
|
|
240
|
+
"collection": "executedagreements",
|
|
241
|
+
"tableName": "executed_agreement_collections",
|
|
242
|
+
"packageName": "@happyvertical/smrt-sales",
|
|
243
|
+
"extends": "SmrtCollection",
|
|
244
|
+
"fields": [],
|
|
245
|
+
"relationships": [],
|
|
246
|
+
"methods": [
|
|
247
|
+
"createImmutable",
|
|
248
|
+
"effectiveForSource",
|
|
249
|
+
"findByExecution",
|
|
250
|
+
"findVersionsBySource"
|
|
251
|
+
],
|
|
252
|
+
"methodSignatures": [
|
|
253
|
+
{
|
|
254
|
+
"name": "createImmutable",
|
|
255
|
+
"async": true,
|
|
256
|
+
"params": [
|
|
257
|
+
"options: ExecutedAgreementOptions"
|
|
258
|
+
],
|
|
259
|
+
"returns": "Promise<object>"
|
|
260
|
+
},
|
|
261
|
+
{
|
|
262
|
+
"name": "effectiveForSource",
|
|
263
|
+
"async": true,
|
|
264
|
+
"params": [
|
|
265
|
+
"sourceKind: string",
|
|
266
|
+
"sourceId: string",
|
|
267
|
+
"at?: Date"
|
|
268
|
+
],
|
|
269
|
+
"returns": "Promise<ExecutedAgreement | null>"
|
|
270
|
+
},
|
|
271
|
+
{
|
|
272
|
+
"name": "findByExecution",
|
|
273
|
+
"async": true,
|
|
274
|
+
"params": [
|
|
275
|
+
"executionId: string"
|
|
276
|
+
],
|
|
277
|
+
"returns": "Promise<ExecutedAgreement | null>"
|
|
278
|
+
},
|
|
279
|
+
{
|
|
280
|
+
"name": "findVersionsBySource",
|
|
281
|
+
"async": true,
|
|
282
|
+
"params": [
|
|
283
|
+
"sourceKind: string",
|
|
284
|
+
"sourceId: string"
|
|
285
|
+
],
|
|
286
|
+
"returns": "Promise<ExecutedAgreement[]>"
|
|
287
|
+
}
|
|
288
|
+
],
|
|
289
|
+
"surfaces": [],
|
|
290
|
+
"relationshipFeatures": [
|
|
291
|
+
"uuidColumns"
|
|
292
|
+
],
|
|
293
|
+
"tags": [],
|
|
294
|
+
"risks": []
|
|
295
|
+
},
|
|
59
296
|
{
|
|
60
297
|
"name": "AgreementExecution",
|
|
61
298
|
"qualifiedName": "@happyvertical/smrt-sales:AgreementExecution",
|
|
@@ -709,360 +946,123 @@
|
|
|
709
946
|
"columnType": "TIMESTAMP"
|
|
710
947
|
},
|
|
711
948
|
{
|
|
712
|
-
"name": "supersedesExecutedAgreementId",
|
|
713
|
-
"type": "foreignKey",
|
|
714
|
-
"required": false,
|
|
715
|
-
"related": "ExecutedAgreement",
|
|
716
|
-
"columnType": "UUID"
|
|
717
|
-
},
|
|
718
|
-
{
|
|
719
|
-
"name": "metadata",
|
|
720
|
-
"type": "text",
|
|
721
|
-
"required": false,
|
|
722
|
-
"columnType": "TEXT",
|
|
723
|
-
"default": "{}"
|
|
724
|
-
}
|
|
725
|
-
],
|
|
726
|
-
"relationships": [
|
|
727
|
-
{
|
|
728
|
-
"name": "executionId",
|
|
729
|
-
"type": "foreignKey",
|
|
730
|
-
"required": true,
|
|
731
|
-
"related": "AgreementExecution",
|
|
732
|
-
"columnType": "UUID"
|
|
733
|
-
},
|
|
734
|
-
{
|
|
735
|
-
"name": "sourceAssetId",
|
|
736
|
-
"type": "crossPackageRef",
|
|
737
|
-
"required": false,
|
|
738
|
-
"related": "@happyvertical/smrt-assets:Asset",
|
|
739
|
-
"columnType": "UUID"
|
|
740
|
-
},
|
|
741
|
-
{
|
|
742
|
-
"name": "signedDocumentAssetId",
|
|
743
|
-
"type": "crossPackageRef",
|
|
744
|
-
"required": false,
|
|
745
|
-
"related": "@happyvertical/smrt-assets:Asset",
|
|
746
|
-
"columnType": "UUID"
|
|
747
|
-
},
|
|
748
|
-
{
|
|
749
|
-
"name": "auditTrailAssetId",
|
|
750
|
-
"type": "crossPackageRef",
|
|
751
|
-
"required": false,
|
|
752
|
-
"related": "@happyvertical/smrt-assets:Asset",
|
|
753
|
-
"columnType": "UUID"
|
|
754
|
-
},
|
|
755
|
-
{
|
|
756
|
-
"name": "supersedesExecutedAgreementId",
|
|
757
|
-
"type": "foreignKey",
|
|
758
|
-
"required": false,
|
|
759
|
-
"related": "ExecutedAgreement",
|
|
760
|
-
"columnType": "UUID"
|
|
761
|
-
}
|
|
762
|
-
],
|
|
763
|
-
"methods": [
|
|
764
|
-
"initialize",
|
|
765
|
-
"isEffectiveAt",
|
|
766
|
-
"save"
|
|
767
|
-
],
|
|
768
|
-
"methodSignatures": [
|
|
769
|
-
{
|
|
770
|
-
"name": "initialize",
|
|
771
|
-
"async": true,
|
|
772
|
-
"returns": "Promise"
|
|
773
|
-
},
|
|
774
|
-
{
|
|
775
|
-
"name": "isEffectiveAt",
|
|
776
|
-
"params": [
|
|
777
|
-
"at: Date"
|
|
778
|
-
],
|
|
779
|
-
"returns": "boolean"
|
|
780
|
-
},
|
|
781
|
-
{
|
|
782
|
-
"name": "save",
|
|
783
|
-
"async": true,
|
|
784
|
-
"returns": "Promise"
|
|
785
|
-
}
|
|
786
|
-
],
|
|
787
|
-
"tenant": {
|
|
788
|
-
"scoped": true,
|
|
789
|
-
"mode": "required",
|
|
790
|
-
"field": "tenantId"
|
|
791
|
-
},
|
|
792
|
-
"conflictColumns": [
|
|
793
|
-
"tenant_id",
|
|
794
|
-
"execution_id"
|
|
795
|
-
],
|
|
796
|
-
"surfaces": [
|
|
797
|
-
{
|
|
798
|
-
"kind": "api",
|
|
799
|
-
"name": "executedagreements.list",
|
|
800
|
-
"operation": "list",
|
|
801
|
-
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
|
|
802
|
-
"path": "/executedagreements",
|
|
803
|
-
"method": "GET"
|
|
804
|
-
},
|
|
805
|
-
{
|
|
806
|
-
"kind": "api",
|
|
807
|
-
"name": "executedagreements.get",
|
|
808
|
-
"operation": "get",
|
|
809
|
-
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
|
|
810
|
-
"path": "/executedagreements/[id]",
|
|
811
|
-
"method": "GET"
|
|
812
|
-
},
|
|
813
|
-
{
|
|
814
|
-
"kind": "mcp",
|
|
815
|
-
"name": "executedagreement_list",
|
|
816
|
-
"operation": "list",
|
|
817
|
-
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
|
|
818
|
-
},
|
|
819
|
-
{
|
|
820
|
-
"kind": "mcp",
|
|
821
|
-
"name": "executedagreement_get",
|
|
822
|
-
"operation": "get",
|
|
823
|
-
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
|
|
824
|
-
}
|
|
825
|
-
],
|
|
826
|
-
"relationshipFeatures": [
|
|
827
|
-
"crossPackageRef",
|
|
828
|
-
"foreignKey",
|
|
829
|
-
"uuidColumns"
|
|
830
|
-
],
|
|
831
|
-
"tags": [],
|
|
832
|
-
"risks": []
|
|
833
|
-
},
|
|
834
|
-
{
|
|
835
|
-
"name": "AgreementExecutionCollection",
|
|
836
|
-
"qualifiedName": "@happyvertical/smrt-sales:AgreementExecutionCollection",
|
|
837
|
-
"collection": "agreementexecutions",
|
|
838
|
-
"tableName": "agreement_execution_collections",
|
|
839
|
-
"packageName": "@happyvertical/smrt-sales",
|
|
840
|
-
"extends": "SmrtCollection",
|
|
841
|
-
"fields": [],
|
|
842
|
-
"relationships": [],
|
|
843
|
-
"methods": [
|
|
844
|
-
"bindEvidenceArtifact",
|
|
845
|
-
"bindProviderRequest",
|
|
846
|
-
"claimCreateAttempt",
|
|
847
|
-
"compareAndSetLifecycle",
|
|
848
|
-
"completeCreateAttempt",
|
|
849
|
-
"failCreateAttempt",
|
|
850
|
-
"findByIdempotencyKey",
|
|
851
|
-
"findByProviderRequest",
|
|
852
|
-
"findBySource",
|
|
853
|
-
"incrementAttemptCount",
|
|
854
|
-
"updateLastError"
|
|
855
|
-
],
|
|
856
|
-
"methodSignatures": [
|
|
857
|
-
{
|
|
858
|
-
"name": "bindEvidenceArtifact",
|
|
859
|
-
"async": true,
|
|
860
|
-
"params": [
|
|
861
|
-
"input: BindAgreementEvidenceArtifactInput"
|
|
862
|
-
],
|
|
863
|
-
"returns": "Promise<AgreementExecution | null>"
|
|
864
|
-
},
|
|
865
|
-
{
|
|
866
|
-
"name": "bindProviderRequest",
|
|
867
|
-
"async": true,
|
|
868
|
-
"params": [
|
|
869
|
-
"input: BindAgreementProviderRequestInput"
|
|
870
|
-
],
|
|
871
|
-
"returns": "Promise<AgreementExecution | null>"
|
|
872
|
-
},
|
|
873
|
-
{
|
|
874
|
-
"name": "claimCreateAttempt",
|
|
875
|
-
"async": true,
|
|
876
|
-
"params": [
|
|
877
|
-
"input: ClaimAgreementCreateAttemptInput"
|
|
878
|
-
],
|
|
879
|
-
"returns": "Promise<AgreementExecution | null>"
|
|
880
|
-
},
|
|
881
|
-
{
|
|
882
|
-
"name": "compareAndSetLifecycle",
|
|
883
|
-
"async": true,
|
|
884
|
-
"params": [
|
|
885
|
-
"input: CompareAndSetAgreementLifecycleInput"
|
|
886
|
-
],
|
|
887
|
-
"returns": "Promise<AgreementExecution | null>"
|
|
888
|
-
},
|
|
889
|
-
{
|
|
890
|
-
"name": "completeCreateAttempt",
|
|
891
|
-
"async": true,
|
|
892
|
-
"params": [
|
|
893
|
-
"input: CompleteAgreementCreateAttemptInput"
|
|
894
|
-
],
|
|
895
|
-
"returns": "Promise<AgreementExecution | null>"
|
|
949
|
+
"name": "supersedesExecutedAgreementId",
|
|
950
|
+
"type": "foreignKey",
|
|
951
|
+
"required": false,
|
|
952
|
+
"related": "ExecutedAgreement",
|
|
953
|
+
"columnType": "UUID"
|
|
896
954
|
},
|
|
897
955
|
{
|
|
898
|
-
"name": "
|
|
899
|
-
"
|
|
900
|
-
"
|
|
901
|
-
|
|
902
|
-
|
|
903
|
-
|
|
904
|
-
|
|
956
|
+
"name": "metadata",
|
|
957
|
+
"type": "text",
|
|
958
|
+
"required": false,
|
|
959
|
+
"columnType": "TEXT",
|
|
960
|
+
"default": "{}"
|
|
961
|
+
}
|
|
962
|
+
],
|
|
963
|
+
"relationships": [
|
|
905
964
|
{
|
|
906
|
-
"name": "
|
|
907
|
-
"
|
|
908
|
-
"
|
|
909
|
-
|
|
910
|
-
|
|
911
|
-
"returns": "Promise<AgreementExecution | null>"
|
|
965
|
+
"name": "executionId",
|
|
966
|
+
"type": "foreignKey",
|
|
967
|
+
"required": true,
|
|
968
|
+
"related": "AgreementExecution",
|
|
969
|
+
"columnType": "UUID"
|
|
912
970
|
},
|
|
913
971
|
{
|
|
914
|
-
"name": "
|
|
915
|
-
"
|
|
916
|
-
"
|
|
917
|
-
|
|
918
|
-
|
|
919
|
-
],
|
|
920
|
-
"returns": "Promise<AgreementExecution | null>"
|
|
972
|
+
"name": "sourceAssetId",
|
|
973
|
+
"type": "crossPackageRef",
|
|
974
|
+
"required": false,
|
|
975
|
+
"related": "@happyvertical/smrt-assets:Asset",
|
|
976
|
+
"columnType": "UUID"
|
|
921
977
|
},
|
|
922
978
|
{
|
|
923
|
-
"name": "
|
|
924
|
-
"
|
|
925
|
-
"
|
|
926
|
-
|
|
927
|
-
|
|
928
|
-
],
|
|
929
|
-
"returns": "Promise<AgreementExecution[]>"
|
|
979
|
+
"name": "signedDocumentAssetId",
|
|
980
|
+
"type": "crossPackageRef",
|
|
981
|
+
"required": false,
|
|
982
|
+
"related": "@happyvertical/smrt-assets:Asset",
|
|
983
|
+
"columnType": "UUID"
|
|
930
984
|
},
|
|
931
985
|
{
|
|
932
|
-
"name": "
|
|
933
|
-
"
|
|
934
|
-
"
|
|
935
|
-
|
|
936
|
-
|
|
937
|
-
],
|
|
938
|
-
"returns": "Promise<AgreementExecution>"
|
|
986
|
+
"name": "auditTrailAssetId",
|
|
987
|
+
"type": "crossPackageRef",
|
|
988
|
+
"required": false,
|
|
989
|
+
"related": "@happyvertical/smrt-assets:Asset",
|
|
990
|
+
"columnType": "UUID"
|
|
939
991
|
},
|
|
940
992
|
{
|
|
941
|
-
"name": "
|
|
942
|
-
"
|
|
943
|
-
"
|
|
944
|
-
|
|
945
|
-
|
|
946
|
-
"returns": "Promise<AgreementExecution>"
|
|
993
|
+
"name": "supersedesExecutedAgreementId",
|
|
994
|
+
"type": "foreignKey",
|
|
995
|
+
"required": false,
|
|
996
|
+
"related": "ExecutedAgreement",
|
|
997
|
+
"columnType": "UUID"
|
|
947
998
|
}
|
|
948
999
|
],
|
|
949
|
-
"surfaces": [],
|
|
950
|
-
"relationshipFeatures": [
|
|
951
|
-
"uuidColumns"
|
|
952
|
-
],
|
|
953
|
-
"tags": [],
|
|
954
|
-
"risks": []
|
|
955
|
-
},
|
|
956
|
-
{
|
|
957
|
-
"name": "AgreementExecutionEventCollection",
|
|
958
|
-
"qualifiedName": "@happyvertical/smrt-sales:AgreementExecutionEventCollection",
|
|
959
|
-
"collection": "agreementexecutionevents",
|
|
960
|
-
"tableName": "agreement_execution_event_collections",
|
|
961
|
-
"packageName": "@happyvertical/smrt-sales",
|
|
962
|
-
"extends": "SmrtCollection",
|
|
963
|
-
"fields": [],
|
|
964
|
-
"relationships": [],
|
|
965
1000
|
"methods": [
|
|
966
|
-
"
|
|
967
|
-
"
|
|
968
|
-
"
|
|
969
|
-
"recordVerified"
|
|
1001
|
+
"initialize",
|
|
1002
|
+
"isEffectiveAt",
|
|
1003
|
+
"save"
|
|
970
1004
|
],
|
|
971
1005
|
"methodSignatures": [
|
|
972
1006
|
{
|
|
973
|
-
"name": "
|
|
974
|
-
"async": true,
|
|
975
|
-
"params": [
|
|
976
|
-
"dedupeKey: string"
|
|
977
|
-
],
|
|
978
|
-
"returns": "Promise<AgreementExecutionEvent | null>"
|
|
979
|
-
},
|
|
980
|
-
{
|
|
981
|
-
"name": "findByExecution",
|
|
1007
|
+
"name": "initialize",
|
|
982
1008
|
"async": true,
|
|
983
|
-
"
|
|
984
|
-
"executionId: string"
|
|
985
|
-
],
|
|
986
|
-
"returns": "Promise<AgreementExecutionEvent[]>"
|
|
1009
|
+
"returns": "Promise"
|
|
987
1010
|
},
|
|
988
1011
|
{
|
|
989
|
-
"name": "
|
|
990
|
-
"async": true,
|
|
1012
|
+
"name": "isEffectiveAt",
|
|
991
1013
|
"params": [
|
|
992
|
-
"
|
|
1014
|
+
"at: Date"
|
|
993
1015
|
],
|
|
994
|
-
"returns": "
|
|
1016
|
+
"returns": "boolean"
|
|
995
1017
|
},
|
|
996
1018
|
{
|
|
997
|
-
"name": "
|
|
1019
|
+
"name": "save",
|
|
998
1020
|
"async": true,
|
|
999
|
-
"
|
|
1000
|
-
"options: VerifiedAgreementExecutionEventOptions"
|
|
1001
|
-
],
|
|
1002
|
-
"returns": "Promise<object>"
|
|
1021
|
+
"returns": "Promise"
|
|
1003
1022
|
}
|
|
1004
1023
|
],
|
|
1005
|
-
"
|
|
1006
|
-
|
|
1007
|
-
"
|
|
1008
|
-
|
|
1009
|
-
|
|
1010
|
-
"
|
|
1011
|
-
|
|
1012
|
-
|
|
1013
|
-
"name": "ExecutedAgreementCollection",
|
|
1014
|
-
"qualifiedName": "@happyvertical/smrt-sales:ExecutedAgreementCollection",
|
|
1015
|
-
"collection": "executedagreements",
|
|
1016
|
-
"tableName": "executed_agreement_collections",
|
|
1017
|
-
"packageName": "@happyvertical/smrt-sales",
|
|
1018
|
-
"extends": "SmrtCollection",
|
|
1019
|
-
"fields": [],
|
|
1020
|
-
"relationships": [],
|
|
1021
|
-
"methods": [
|
|
1022
|
-
"createImmutable",
|
|
1023
|
-
"effectiveForSource",
|
|
1024
|
-
"findByExecution",
|
|
1025
|
-
"findVersionsBySource"
|
|
1024
|
+
"tenant": {
|
|
1025
|
+
"scoped": true,
|
|
1026
|
+
"mode": "required",
|
|
1027
|
+
"field": "tenantId"
|
|
1028
|
+
},
|
|
1029
|
+
"conflictColumns": [
|
|
1030
|
+
"tenant_id",
|
|
1031
|
+
"execution_id"
|
|
1026
1032
|
],
|
|
1027
|
-
"
|
|
1033
|
+
"surfaces": [
|
|
1028
1034
|
{
|
|
1029
|
-
"
|
|
1030
|
-
"
|
|
1031
|
-
"
|
|
1032
|
-
|
|
1033
|
-
|
|
1034
|
-
"
|
|
1035
|
+
"kind": "api",
|
|
1036
|
+
"name": "executedagreements.list",
|
|
1037
|
+
"operation": "list",
|
|
1038
|
+
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
|
|
1039
|
+
"path": "/executedagreements",
|
|
1040
|
+
"method": "GET"
|
|
1035
1041
|
},
|
|
1036
1042
|
{
|
|
1037
|
-
"
|
|
1038
|
-
"
|
|
1039
|
-
"
|
|
1040
|
-
|
|
1041
|
-
|
|
1042
|
-
|
|
1043
|
-
],
|
|
1044
|
-
"returns": "Promise<ExecutedAgreement | null>"
|
|
1043
|
+
"kind": "api",
|
|
1044
|
+
"name": "executedagreements.get",
|
|
1045
|
+
"operation": "get",
|
|
1046
|
+
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement",
|
|
1047
|
+
"path": "/executedagreements/[id]",
|
|
1048
|
+
"method": "GET"
|
|
1045
1049
|
},
|
|
1046
1050
|
{
|
|
1047
|
-
"
|
|
1048
|
-
"
|
|
1049
|
-
"
|
|
1050
|
-
|
|
1051
|
-
],
|
|
1052
|
-
"returns": "Promise<ExecutedAgreement | null>"
|
|
1051
|
+
"kind": "mcp",
|
|
1052
|
+
"name": "executedagreement_list",
|
|
1053
|
+
"operation": "list",
|
|
1054
|
+
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
|
|
1053
1055
|
},
|
|
1054
1056
|
{
|
|
1055
|
-
"
|
|
1056
|
-
"
|
|
1057
|
-
"
|
|
1058
|
-
|
|
1059
|
-
"sourceId: string"
|
|
1060
|
-
],
|
|
1061
|
-
"returns": "Promise<ExecutedAgreement[]>"
|
|
1057
|
+
"kind": "mcp",
|
|
1058
|
+
"name": "executedagreement_get",
|
|
1059
|
+
"operation": "get",
|
|
1060
|
+
"objectName": "@happyvertical/smrt-sales:ExecutedAgreement"
|
|
1062
1061
|
}
|
|
1063
1062
|
],
|
|
1064
|
-
"surfaces": [],
|
|
1065
1063
|
"relationshipFeatures": [
|
|
1064
|
+
"crossPackageRef",
|
|
1065
|
+
"foreignKey",
|
|
1066
1066
|
"uuidColumns"
|
|
1067
1067
|
],
|
|
1068
1068
|
"tags": [],
|
|
@@ -2084,6 +2084,11 @@
|
|
|
2084
2084
|
"mode": "optional",
|
|
2085
2085
|
"field": "tenantId"
|
|
2086
2086
|
},
|
|
2087
|
+
"conflictColumns": [
|
|
2088
|
+
"tenant_id",
|
|
2089
|
+
"slug",
|
|
2090
|
+
"context"
|
|
2091
|
+
],
|
|
2087
2092
|
"surfaces": [
|
|
2088
2093
|
{
|
|
2089
2094
|
"kind": "api",
|
|
@@ -2159,6 +2164,11 @@
|
|
|
2159
2164
|
"mode": "required",
|
|
2160
2165
|
"field": "tenantId"
|
|
2161
2166
|
},
|
|
2167
|
+
"conflictColumns": [
|
|
2168
|
+
"tenant_id",
|
|
2169
|
+
"slug",
|
|
2170
|
+
"context"
|
|
2171
|
+
],
|
|
2162
2172
|
"surfaces": [],
|
|
2163
2173
|
"relationshipFeatures": [
|
|
2164
2174
|
"uuidColumns"
|
|
@@ -2828,6 +2838,11 @@
|
|
|
2828
2838
|
"mode": "optional",
|
|
2829
2839
|
"field": "tenantId"
|
|
2830
2840
|
},
|
|
2841
|
+
"conflictColumns": [
|
|
2842
|
+
"tenant_id",
|
|
2843
|
+
"slug",
|
|
2844
|
+
"context"
|
|
2845
|
+
],
|
|
2831
2846
|
"surfaces": [
|
|
2832
2847
|
{
|
|
2833
2848
|
"kind": "api",
|
|
@@ -3797,6 +3812,11 @@
|
|
|
3797
3812
|
"mode": "optional",
|
|
3798
3813
|
"field": "tenantId"
|
|
3799
3814
|
},
|
|
3815
|
+
"conflictColumns": [
|
|
3816
|
+
"tenant_id",
|
|
3817
|
+
"slug",
|
|
3818
|
+
"context"
|
|
3819
|
+
],
|
|
3800
3820
|
"surfaces": [
|
|
3801
3821
|
{
|
|
3802
3822
|
"kind": "api",
|
|
@@ -4085,6 +4105,11 @@
|
|
|
4085
4105
|
"mode": "optional",
|
|
4086
4106
|
"field": "tenantId"
|
|
4087
4107
|
},
|
|
4108
|
+
"conflictColumns": [
|
|
4109
|
+
"tenant_id",
|
|
4110
|
+
"slug",
|
|
4111
|
+
"context"
|
|
4112
|
+
],
|
|
4088
4113
|
"surfaces": [
|
|
4089
4114
|
{
|
|
4090
4115
|
"kind": "api",
|
|
@@ -4744,6 +4769,11 @@
|
|
|
4744
4769
|
"mode": "optional",
|
|
4745
4770
|
"field": "tenantId"
|
|
4746
4771
|
},
|
|
4772
|
+
"conflictColumns": [
|
|
4773
|
+
"tenant_id",
|
|
4774
|
+
"slug",
|
|
4775
|
+
"context"
|
|
4776
|
+
],
|
|
4747
4777
|
"surfaces": [
|
|
4748
4778
|
{
|
|
4749
4779
|
"kind": "api",
|
|
@@ -4882,6 +4912,11 @@
|
|
|
4882
4912
|
"mode": "optional",
|
|
4883
4913
|
"field": "tenantId"
|
|
4884
4914
|
},
|
|
4915
|
+
"conflictColumns": [
|
|
4916
|
+
"tenant_id",
|
|
4917
|
+
"slug",
|
|
4918
|
+
"context"
|
|
4919
|
+
],
|
|
4885
4920
|
"surfaces": [
|
|
4886
4921
|
{
|
|
4887
4922
|
"kind": "api",
|
|
@@ -5622,6 +5657,11 @@
|
|
|
5622
5657
|
"mode": "optional",
|
|
5623
5658
|
"field": "tenantId"
|
|
5624
5659
|
},
|
|
5660
|
+
"conflictColumns": [
|
|
5661
|
+
"tenant_id",
|
|
5662
|
+
"slug",
|
|
5663
|
+
"context"
|
|
5664
|
+
],
|
|
5625
5665
|
"surfaces": [
|
|
5626
5666
|
{
|
|
5627
5667
|
"kind": "api",
|
|
@@ -6163,6 +6203,11 @@
|
|
|
6163
6203
|
"mode": "optional",
|
|
6164
6204
|
"field": "tenantId"
|
|
6165
6205
|
},
|
|
6206
|
+
"conflictColumns": [
|
|
6207
|
+
"tenant_id",
|
|
6208
|
+
"slug",
|
|
6209
|
+
"context"
|
|
6210
|
+
],
|
|
6166
6211
|
"surfaces": [
|
|
6167
6212
|
{
|
|
6168
6213
|
"kind": "api",
|
|
@@ -6608,6 +6653,11 @@
|
|
|
6608
6653
|
"mode": "optional",
|
|
6609
6654
|
"field": "tenantId"
|
|
6610
6655
|
},
|
|
6656
|
+
"conflictColumns": [
|
|
6657
|
+
"tenant_id",
|
|
6658
|
+
"slug",
|
|
6659
|
+
"context"
|
|
6660
|
+
],
|
|
6611
6661
|
"surfaces": [],
|
|
6612
6662
|
"relationshipFeatures": [
|
|
6613
6663
|
"uuidColumns"
|
|
@@ -7137,6 +7187,11 @@
|
|
|
7137
7187
|
"mode": "optional",
|
|
7138
7188
|
"field": "tenantId"
|
|
7139
7189
|
},
|
|
7190
|
+
"conflictColumns": [
|
|
7191
|
+
"tenant_id",
|
|
7192
|
+
"slug",
|
|
7193
|
+
"context"
|
|
7194
|
+
],
|
|
7140
7195
|
"surfaces": [
|
|
7141
7196
|
{
|
|
7142
7197
|
"kind": "api",
|
|
@@ -7322,6 +7377,11 @@
|
|
|
7322
7377
|
"mode": "optional",
|
|
7323
7378
|
"field": "tenantId"
|
|
7324
7379
|
},
|
|
7380
|
+
"conflictColumns": [
|
|
7381
|
+
"tenant_id",
|
|
7382
|
+
"slug",
|
|
7383
|
+
"context"
|
|
7384
|
+
],
|
|
7325
7385
|
"surfaces": [
|
|
7326
7386
|
{
|
|
7327
7387
|
"kind": "api",
|
|
@@ -7470,6 +7530,11 @@
|
|
|
7470
7530
|
"mode": "optional",
|
|
7471
7531
|
"field": "tenantId"
|
|
7472
7532
|
},
|
|
7533
|
+
"conflictColumns": [
|
|
7534
|
+
"tenant_id",
|
|
7535
|
+
"slug",
|
|
7536
|
+
"context"
|
|
7537
|
+
],
|
|
7473
7538
|
"surfaces": [
|
|
7474
7539
|
{
|
|
7475
7540
|
"kind": "api",
|
|
@@ -8910,7 +8975,7 @@
|
|
|
8910
8975
|
"polymorphicAssociations": 0,
|
|
8911
8976
|
"uuidColumns": 136
|
|
8912
8977
|
},
|
|
8913
|
-
"agentDoc": "# @happyvertical/smrt-sales\n\nModular sales: provider-neutral agreement execution, CRM, referral intake, a neutral commissions financial core, and reusable Svelte surfaces. One installable package with distinct subpath exports:\n\n- `@happyvertical/smrt-sales/agreements`\n- `@happyvertical/smrt-sales/crm`\n- `@happyvertical/smrt-sales/referrals`\n- `@happyvertical/smrt-sales/commissions`\n- `@happyvertical/smrt-sales/svelte`\n\nThe root export re-exports every TS module. `agreements` depends on the provider-neutral `@happyvertical/signatures` contract and `smrt-assets`; provider credentials stay in the injected SDK adapter/secret store. `referrals` binds its versioned terms to `agreements`.\n\n## Validation\n\nRun `pnpm --filter @happyvertical/smrt-sales test` and `pnpm --filter @happyvertical/smrt-sales typecheck` for package changes. PostgreSQL-sensitive changes must also run `pnpm --filter @happyvertical/smrt-sales test:postgres`; the command uses the repository's disposable PostgreSQL harness and is registered in the PostgreSQL CI shard.\n\n## Roles vs. money\n\nReferrers and Sales Representatives are **distinct roles** and stay that way. Both connect to money through one neutral financial account:\n\n- **Earner** (commissions): payout identity — method, threshold, currency, status. Referenced by every Commission and CommissionPayout.\n- **SalesRepresentative** (crm) and **Referrer** (referrals): role models, each holding `profileId` (cross-package string ref to smrt-profiles) and `earnerId`.\n\n## Modules\n\nPer-module semantics live in sibling module docs — read the one for the module\nyou are editing. This file keeps what holds in every module.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `agreements` | verified execution evidence — private orchestration state, append-only provider events, immutable executed agreements, and the provider-neutral execution service | [agents/agreements.md](agents/agreements.md) |\n| `commissions` | the neutral financial core — earners, versioned plans, earning events, commissions, adjustments, balances, and payout settlement | [agents/commissions.md](agents/commissions.md) |\n| `crm` | leads, configurable pipelines, opportunities, tenant-safe Lead follow-up, activity trail, and idempotent conversion links | [agents/crm.md](agents/crm.md) |\n| `referrals` | referrers, programs, versioned attribution policies, links/touches, referrals, exception review, and term snapshots | [agents/referrals.md](agents/referrals.md) |\n| `svelte` | props-driven presentational surfaces for CRM, the referrer portal, and operator review | [agents/svelte.md](agents/svelte.md) |\n\n## Currency\n\n**All monetary fields are integer cents** with `*Cents` suffixes; rates are decimal (`0`–`1`). Rounding happens once per calculation step via `roundCents()` (half-away-from-zero) and every Commission stores its `calculationTrace` so amounts are reproducible. Convert at display/commerce boundaries with `centsToAmount()`/`amountToCents()`.\n\n## Tenancy\n\nBusiness/domain models are generally `@TenantScoped({ mode: 'optional' })` with `@tenantId({ nullable: true })`. This deliberately departs from legacy smrt-affiliates (which was cross-tenant by design for ad networks): sales programs, earners, and payouts are tenant-owned, while `tenantId: null` remains available for intentional global/operator-level rows. Immutable tenant-bound execution evidence (`AgreementExecution`, `AgreementExecutionEvent`, `ExecutedAgreement`) and private orchestration fences (`CommissionAdjustmentOperation`) instead use required tenancy with a non-null owner; never weaken those rows to optional tenancy.\n\n## Cross-package references (plain strings)\n\n`profileId` → smrt-profiles Profile; `invoiceId` (CommissionPayout) → smrt-commerce Invoice; agreement artifacts → smrt-assets Asset ids. No static imports of unrelated sibling domain packages.\n\n## smrt-affiliates migration\n\n`@happyvertical/smrt-affiliates` is now a deprecated compatibility package that re-exports this package's commissions core under the legacy names (`Partner` → `Earner`, `Payout` → `CommissionPayout`, `Commission`, collections, enums) with `@deprecated` guidance and **no duplicate persistence model**. The data/API mapping lives in `packages/affiliates/MIGRATION.md`.\n\n## Gotchas\n\n- **Cents vs. rates**: `*Cents` fields are INTEGER (`= 0` defaults); `rate`/`probability`/`shareFraction` are DECIMAL (`= 0.0` defaults). Don't mix the two conventions on one field.\n- **Versioned terms are rows, not edits**: CommissionPlan / AttributionPolicy / ReferralAgreement amendments insert `version + 1`; active versions are save-guarded immutable.\n- **Idempotency is dedupeKey-based**: EarningEvent, Commission, and CommissionPayout carry natural keys (`conflictColumns`) — retried ingestion/settlement upserts instead of duplicating.\n- **Adjustments never rewrite**: correcting an earned/paid Commission means appending a CommissionAdjustment, not editing the Commission.\n- **Adjustment retries use the service**: CommissionAdjustment has no public operation field and rejects an untyped `operationId` constructor option; ordinary legacy creates without one remain compatible. `CommissionAdjustmentService` transactionally claims the private operation fence with insert-on-conflict-no-op, creates the explicit mapped adjustment id only for the winner, then verifies the persisted intent; the same globally unique operation UUID cannot be reused by another tenant.\n- **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.\n- **CommissionPayout, not Payout**: avoids the pre-existing global table-name collision between commerce `Payout` and legacy affiliates `Payout` (`payouts`).\n- **Table names are global**: new models were named to avoid collisions across packages (`commission_payouts`, `sales_activities`, `attribution_policies`, …).\n- **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`.\n- **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.\n- **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.\n- **`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.\n- **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.\n- **`sweepClearing` treats `clearingEndsAt: null` as immediately sweepable** (no clearing configured ⇒ nothing to wait for).\n- **Agreement freeze scope**: activating a ReferralAgreement requires and freezes its execution/evidence refs along with its commercial terms. `effectiveTo` remains writable for explicit end-dating; signed bytes, hashes, signer evidence, and audit trail exist only on immutable ExecutedAgreement/Asset records.\n- **Circular FK pair by design**: `Referral.snapshotId ↔ ReferralTermSnapshot.referralId`. Fine on SQLite (and no cross-table DDL constraints are emitted for these string FKs); keep an eye on strict-DDL environments.\n- **Attribution resolution is single-writer per (target, program)**: `resolve()` is idempotent against PERSISTED state, but two workers resolving the same target concurrently can both pass the existence check and create duplicate credit — the collection layer has no cross-row transaction (the same stance as payout batching, which relies on disjoint scopes for concurrency). Run intake resolution serially per target (it naturally is, in a request handler); duplicates are visible in the portal and correctable via `override()`.\n- **recordClick inside your transaction participates, never nests**: a nested adapter `transaction()` takes an independent pooled connection (happyvertical/sdk#1108) — it deadlocks undetectably on locks the caller's transaction holds (PostgreSQL sees a promise-wait, not a lock-wait) and refuses caller-created uncommitted links as `unknown_code`. Pass the caller's transaction database as `RecordClickInput.transaction` or bind the collection to it (`{ db: tx, _reuseInitializedDb: true, _deferRuntimeInitialization: true }` — detected and honored automatically); a pool-level database passed as `transaction` is refused with typed reason `invalid_transaction`. Participating results are bound to the caller's transaction — carry ids across the commit boundary; the pool-bound default still self-transacts and rehydrates after commit.\n- **Click retries reuse one key**: pass the exact same non-empty, well-formed-Unicode `recordClick.idempotencyKey` (maximum 256 UTF-8 bytes) on transport/database retry. Omitting it remains source-compatible but creates and returns a one-shot UUID; it cannot deduplicate a later independent invocation. `maxEvidenceBytes` guards creation; changing it cannot turn an already-committed exact replay into failure. Replay validation is against the immutable operation/touch snapshot, not mutable current link fields: later link edits preserve exact replay, the result link is current, and the touch evidence is the original snapshot. The private optional-tenant `ReferralClickOperation` table is the serialization fence and must be included in schema migration. Never pre-bound caller evidence: Sales owns the authoritative final-envelope byte check.\n- **`ObjectRegistry.getConfig(X)` needs the class module imported** (decorator side effects) — manifest-only registration doesn't carry api/mcp/conflictColumns; tests asserting surface configs need a side-effect import of the module barrel.\n",
|
|
8978
|
+
"agentDoc": "# @happyvertical/smrt-sales\n\nModular sales: provider-neutral agreement execution, CRM, referral intake, a neutral commissions financial core, and reusable Svelte surfaces. One installable package with distinct subpath exports:\n\n- `@happyvertical/smrt-sales/agreements`\n- `@happyvertical/smrt-sales/crm`\n- `@happyvertical/smrt-sales/referrals`\n- `@happyvertical/smrt-sales/commissions`\n- `@happyvertical/smrt-sales/svelte`\n\nThe root export re-exports every TS module. `agreements` depends on the provider-neutral `@happyvertical/signatures` contract and `smrt-assets`; provider credentials stay in the injected SDK adapter/secret store. `referrals` binds its versioned terms to `agreements`.\n\n## Validation\n\nRun `pnpm --filter @happyvertical/smrt-sales test` and `pnpm --filter @happyvertical/smrt-sales typecheck` for package changes. PostgreSQL-sensitive changes must also run `pnpm --filter @happyvertical/smrt-sales test:postgres`; the command uses the repository's disposable PostgreSQL harness and is registered in the PostgreSQL CI shard.\n\n## Roles vs. money\n\nReferrers and Sales Representatives are **distinct roles** and stay that way. Both connect to money through one neutral financial account:\n\n- **Earner** (commissions): payout identity — method, threshold, currency, status. Referenced by every Commission and CommissionPayout.\n- **SalesRepresentative** (crm) and **Referrer** (referrals): role models, each holding `profileId` (cross-package string ref to smrt-profiles) and `earnerId`.\n\n## Modules\n\nPer-module semantics live in sibling module docs — read the one for the module\nyou are editing. This file keeps what holds in every module.\n\n| Module | Scope | Module doc |\n|---|---|---|\n| `agreements` | verified execution evidence — private orchestration state, append-only provider events, immutable executed agreements, and the provider-neutral execution service | [agents/agreements.md](agents/agreements.md) |\n| `commissions` | the neutral financial core — earners, versioned plans, earning events, commissions, adjustments, balances, and payout settlement | [agents/commissions.md](agents/commissions.md) |\n| `crm` | leads, configurable pipelines, opportunities, tenant-safe Lead follow-up, activity trail, and idempotent conversion links | [agents/crm.md](agents/crm.md) |\n| `referrals` | referrers, programs, versioned attribution policies, links/touches, referrals, exception review, and term snapshots | [agents/referrals.md](agents/referrals.md) |\n| `svelte` | props-driven presentational surfaces for CRM, the referrer portal, and operator review | [agents/svelte.md](agents/svelte.md) |\n\n## Currency\n\n**All monetary fields are integer cents** with `*Cents` suffixes; that scale is a Sales contract, not an implicit framework currency rule. Fresh PostgreSQL/DuckDB INTEGER columns are BIGINT, while JavaScript hydration rejects values outside the safe-integer range. Rates are decimal (`0`–`1`). Rounding happens once per calculation step via `roundCents()` (half-away-from-zero) and every Commission stores its `calculationTrace` so amounts are reproducible. Convert at display/commerce boundaries with `centsToAmount()`/`amountToCents()`.\n\n## Tenancy\n\nBusiness/domain models are generally `@TenantScoped({ mode: 'optional' })` with `@tenantId({ nullable: true })`. This deliberately departs from legacy smrt-affiliates (which was cross-tenant by design for ad networks): sales programs, earners, and payouts are tenant-owned, while `tenantId: null` remains available for intentional global/operator-level rows. Immutable tenant-bound execution evidence (`AgreementExecution`, `AgreementExecutionEvent`, `ExecutedAgreement`) and private orchestration fences (`CommissionAdjustmentOperation`) instead use required tenancy with a non-null owner; never weaken those rows to optional tenancy.\n\n## Cross-package references (plain strings)\n\n`profileId` → smrt-profiles Profile; `invoiceId` (CommissionPayout) → smrt-commerce Invoice; agreement artifacts → smrt-assets Asset ids. No static imports of unrelated sibling domain packages.\n\n## smrt-affiliates migration\n\n`@happyvertical/smrt-affiliates` is now a deprecated compatibility package that re-exports this package's commissions core under the legacy names (`Partner` → `Earner`, `Payout` → `CommissionPayout`, `Commission`, collections, enums) with `@deprecated` guidance and **no duplicate persistence model**. The data/API mapping lives in `packages/affiliates/MIGRATION.md`.\n\n## Gotchas\n\n- **Cents vs. rates**: `*Cents` fields are INTEGER (`= 0` defaults); `rate`/`probability`/`shareFraction` are DECIMAL (`= 0.0` defaults). Don't mix the two conventions on one field.\n- **Versioned terms are rows, not edits**: CommissionPlan / AttributionPolicy / ReferralAgreement amendments insert `version + 1`; active versions are save-guarded immutable.\n- **Idempotency is dedupeKey-based**: EarningEvent, Commission, and CommissionPayout carry natural keys (`conflictColumns`) — retried ingestion/settlement upserts instead of duplicating.\n- **Adjustments never rewrite**: correcting an earned/paid Commission means appending a CommissionAdjustment, not editing the Commission.\n- **Adjustment retries use the service**: CommissionAdjustment has no public operation field and rejects an untyped `operationId` constructor option; ordinary legacy creates without one remain compatible. `CommissionAdjustmentService` transactionally claims the private operation fence with insert-on-conflict-no-op, creates the explicit mapped adjustment id only for the winner, then verifies the persisted intent; the same globally unique operation UUID cannot be reused by another tenant.\n- **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.\n- **CommissionPayout, not Payout**: avoids the pre-existing global table-name collision between commerce `Payout` and legacy affiliates `Payout` (`payouts`).\n- **Table names are global**: new models were named to avoid collisions across packages (`commission_payouts`, `sales_activities`, `attribution_policies`, …).\n- **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`.\n- **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.\n- **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.\n- **`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.\n- **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.\n- **`sweepClearing` treats `clearingEndsAt: null` as immediately sweepable** (no clearing configured ⇒ nothing to wait for).\n- **Agreement freeze scope**: activating a ReferralAgreement requires and freezes its execution/evidence refs along with its commercial terms. `effectiveTo` remains writable for explicit end-dating; signed bytes, hashes, signer evidence, and audit trail exist only on immutable ExecutedAgreement/Asset records.\n- **Circular FK pair by design**: `Referral.snapshotId ↔ ReferralTermSnapshot.referralId`. Fine on SQLite (and no cross-table DDL constraints are emitted for these string FKs); keep an eye on strict-DDL environments.\n- **Attribution resolution is single-writer per (target, program)**: `resolve()` is idempotent against PERSISTED state, but two workers resolving the same target concurrently can both pass the existence check and create duplicate credit — the collection layer has no cross-row transaction (the same stance as payout batching, which relies on disjoint scopes for concurrency). Run intake resolution serially per target (it naturally is, in a request handler); duplicates are visible in the portal and correctable via `override()`.\n- **recordClick inside your transaction participates, never nests**: a nested adapter `transaction()` takes an independent pooled connection (happyvertical/sdk#1108) — it deadlocks undetectably on locks the caller's transaction holds (PostgreSQL sees a promise-wait, not a lock-wait) and refuses caller-created uncommitted links as `unknown_code`. Pass the caller's transaction database as `RecordClickInput.transaction` or bind the collection to it (`{ db: tx, _reuseInitializedDb: true, _deferRuntimeInitialization: true }` — detected and honored automatically); a pool-level database passed as `transaction` is refused with typed reason `invalid_transaction`. Participating results are bound to the caller's transaction — carry ids across the commit boundary; the pool-bound default still self-transacts and rehydrates after commit.\n- **Click retries reuse one key**: pass the exact same non-empty, well-formed-Unicode `recordClick.idempotencyKey` (maximum 256 UTF-8 bytes) on transport/database retry. Omitting it remains source-compatible but creates and returns a one-shot UUID; it cannot deduplicate a later independent invocation. `maxEvidenceBytes` guards creation; changing it cannot turn an already-committed exact replay into failure. Replay validation is against the immutable operation/touch snapshot, not mutable current link fields: later link edits preserve exact replay, the result link is current, and the touch evidence is the original snapshot. The private optional-tenant `ReferralClickOperation` table is the serialization fence and must be included in schema migration. Never pre-bound caller evidence: Sales owns the authoritative final-envelope byte check.\n- **`ObjectRegistry.getConfig(X)` needs the class module imported** (decorator side effects) — manifest-only registration doesn't carry api/mcp/conflictColumns; tests asserting surface configs need a side-effect import of the module barrel.\n",
|
|
8914
8979
|
"moduleDocs": [
|
|
8915
8980
|
{
|
|
8916
8981
|
"path": "agents/agreements.md",
|