@personize/sdk 0.6.2 → 0.6.5
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/README.md +220 -12
- package/dist/client.d.ts +100 -3
- package/dist/client.js +714 -11
- package/dist/types.d.ts +509 -12
- package/package.json +1 -1
package/dist/types.d.ts
CHANGED
|
@@ -65,7 +65,18 @@ export interface GovernanceScope {
|
|
|
65
65
|
/** Action/domain keywords that trigger inclusion (e.g., "email", "pricing", "deploy"). */
|
|
66
66
|
triggerKeywords: string[];
|
|
67
67
|
}
|
|
68
|
-
export interface
|
|
68
|
+
export interface GuidelineListItem {
|
|
69
|
+
id: string;
|
|
70
|
+
type: string;
|
|
71
|
+
name: string;
|
|
72
|
+
value: string;
|
|
73
|
+
/** Compatibility alias commonly used by setup scripts. */
|
|
74
|
+
slug?: string;
|
|
75
|
+
/** Auto-inferred governance scope (read-only). Present when the guideline has been analyzed. */
|
|
76
|
+
governanceScope?: GovernanceScope;
|
|
77
|
+
[key: string]: unknown;
|
|
78
|
+
}
|
|
79
|
+
export interface GuidelinesResponse extends Array<GuidelineListItem> {
|
|
69
80
|
actions: Array<{
|
|
70
81
|
id: string;
|
|
71
82
|
type: string;
|
|
@@ -107,6 +118,8 @@ export interface GuidelineCreatePayload {
|
|
|
107
118
|
description?: string;
|
|
108
119
|
tags?: string[];
|
|
109
120
|
secure?: boolean;
|
|
121
|
+
/** Compatibility alias used by some setup scripts. */
|
|
122
|
+
slug?: string;
|
|
110
123
|
}
|
|
111
124
|
/** @deprecated Use GuidelineCreatePayload instead. */
|
|
112
125
|
export type VariableCreatePayload = GuidelineCreatePayload;
|
|
@@ -142,7 +155,17 @@ export interface GuidelineHistoryOptions {
|
|
|
142
155
|
}
|
|
143
156
|
/** @deprecated Use GuidelineHistoryOptions instead. */
|
|
144
157
|
export type VariableHistoryOptions = GuidelineHistoryOptions;
|
|
145
|
-
export interface
|
|
158
|
+
export interface CollectionListItem {
|
|
159
|
+
id: string;
|
|
160
|
+
type: string;
|
|
161
|
+
collectionName: string;
|
|
162
|
+
collectionId: string;
|
|
163
|
+
/** Compatibility aliases commonly used by setup scripts. */
|
|
164
|
+
name?: string;
|
|
165
|
+
slug?: string;
|
|
166
|
+
[key: string]: unknown;
|
|
167
|
+
}
|
|
168
|
+
export interface CollectionsResponse extends Array<CollectionListItem> {
|
|
146
169
|
actions: Array<{
|
|
147
170
|
id: string;
|
|
148
171
|
type: string;
|
|
@@ -157,19 +180,34 @@ export interface CollectionsResponse {
|
|
|
157
180
|
nextToken?: string;
|
|
158
181
|
}
|
|
159
182
|
export interface CollectionCreatePayload {
|
|
160
|
-
collectionName
|
|
183
|
+
collectionName?: string;
|
|
161
184
|
collectionId?: string;
|
|
162
185
|
definition?: string;
|
|
163
186
|
entityType?: string;
|
|
187
|
+
/** Compatibility alias for collectionName. */
|
|
188
|
+
name?: string;
|
|
189
|
+
/** Compatibility alias for collectionId. */
|
|
190
|
+
slug?: string;
|
|
191
|
+
/** Compatibility alias for definition. */
|
|
192
|
+
description?: string;
|
|
193
|
+
/** Accepted for compatibility; ignored unless the API supports it. */
|
|
194
|
+
icon?: string;
|
|
195
|
+
/** Accepted for compatibility; ignored unless the API supports it. */
|
|
196
|
+
color?: string;
|
|
197
|
+
/** Accepted for compatibility; may be used to infer entityType client-side. */
|
|
198
|
+
primaryKeyField?: string;
|
|
164
199
|
properties?: Array<{
|
|
165
200
|
propertyName: string;
|
|
166
201
|
propertyId?: string;
|
|
167
202
|
systemName?: string;
|
|
168
203
|
type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
|
|
169
|
-
options?: string;
|
|
204
|
+
options?: string | string[];
|
|
170
205
|
description?: string;
|
|
171
206
|
autoSystem?: boolean;
|
|
172
207
|
update?: boolean;
|
|
208
|
+
/** Compatibility alias. `append` maps to `update: false`, `replace` to `update: true`. */
|
|
209
|
+
updateSemantics?: 'replace' | 'append';
|
|
210
|
+
tags?: string[];
|
|
173
211
|
status?: 'Active' | 'Deleted';
|
|
174
212
|
}>;
|
|
175
213
|
status?: 'Active' | 'Deleted';
|
|
@@ -183,10 +221,13 @@ export interface CollectionUpdatePayload {
|
|
|
183
221
|
propertyName?: string;
|
|
184
222
|
systemName?: string;
|
|
185
223
|
type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
|
|
186
|
-
options?: string;
|
|
224
|
+
options?: string | string[];
|
|
187
225
|
description?: string;
|
|
188
226
|
autoSystem?: boolean;
|
|
189
227
|
update?: boolean;
|
|
228
|
+
/** Compatibility alias. `append` maps to `update: false`, `replace` to `update: true`. */
|
|
229
|
+
updateSemantics?: 'replace' | 'append';
|
|
230
|
+
tags?: string[];
|
|
190
231
|
status?: 'Active' | 'Deleted';
|
|
191
232
|
}>;
|
|
192
233
|
status?: 'Active' | 'Deleted';
|
|
@@ -413,6 +454,8 @@ export interface PromptOptions {
|
|
|
413
454
|
* - `{ criteria: 'sales', serverSide: true }` — server-side with preset/custom criteria
|
|
414
455
|
*/
|
|
415
456
|
evaluate?: PromptEvaluateConfig;
|
|
457
|
+
/** Compatibility alias for evaluate: { criteria, serverSide: true }. */
|
|
458
|
+
evaluationCriteria?: string;
|
|
416
459
|
/**
|
|
417
460
|
* Auto-memorize extracted outputs and/or captured tool results.
|
|
418
461
|
* Requires at least one identifier (email, websiteUrl, or recordId).
|
|
@@ -494,6 +537,48 @@ export interface PromptResponse {
|
|
|
494
537
|
stepsExecuted: number;
|
|
495
538
|
}>;
|
|
496
539
|
}
|
|
540
|
+
/** Text chunk from the LLM stream. Many of these per response. */
|
|
541
|
+
export interface SSETextEvent {
|
|
542
|
+
type: 'text';
|
|
543
|
+
chunk: string;
|
|
544
|
+
}
|
|
545
|
+
/** A named output extracted from the stream when its </output> tag closes. One per output. */
|
|
546
|
+
export interface SSEOutputEvent {
|
|
547
|
+
type: 'output';
|
|
548
|
+
name: string;
|
|
549
|
+
data: unknown;
|
|
550
|
+
}
|
|
551
|
+
/** Fired after each instruction step completes (multi-step mode). */
|
|
552
|
+
export interface SSEStepCompleteEvent {
|
|
553
|
+
type: 'step_complete';
|
|
554
|
+
instructionIndex: number;
|
|
555
|
+
text: string;
|
|
556
|
+
toolCalls: Array<{
|
|
557
|
+
toolName: string;
|
|
558
|
+
}>;
|
|
559
|
+
}
|
|
560
|
+
/** Final event — includes all outputs, evaluation, and metadata. */
|
|
561
|
+
export interface SSEDoneEvent {
|
|
562
|
+
type: 'done';
|
|
563
|
+
outputs?: Record<string, unknown>;
|
|
564
|
+
toolOutputs?: Record<string, unknown>;
|
|
565
|
+
evaluation?: unknown;
|
|
566
|
+
metadata?: unknown;
|
|
567
|
+
}
|
|
568
|
+
/** Non-fatal error during streaming. */
|
|
569
|
+
export interface SSEErrorEvent {
|
|
570
|
+
type: 'error';
|
|
571
|
+
message: string;
|
|
572
|
+
}
|
|
573
|
+
/** Union of all SSE event types emitted by the /prompt streaming endpoint. */
|
|
574
|
+
export type PromptSSEEvent = SSETextEvent | SSEOutputEvent | SSEStepCompleteEvent | SSEDoneEvent | SSEErrorEvent;
|
|
575
|
+
/** Options for promptStream(). Extends PromptOptions but forces stream: true. */
|
|
576
|
+
export interface PromptStreamOptions extends Omit<PromptOptions, 'stream'> {
|
|
577
|
+
/** Timeout in milliseconds for the overall stream (default: 120000). */
|
|
578
|
+
streamTimeout?: number;
|
|
579
|
+
/** Abort signal for cancellation. */
|
|
580
|
+
signal?: AbortSignal;
|
|
581
|
+
}
|
|
497
582
|
export interface TestResponse {
|
|
498
583
|
timestamp: string;
|
|
499
584
|
ip: string;
|
|
@@ -563,10 +648,16 @@ export interface MemorizeOptions {
|
|
|
563
648
|
customKeyValue?: string;
|
|
564
649
|
/** Enable enhanced dual extraction (structured + free-form). */
|
|
565
650
|
enhanced?: boolean;
|
|
651
|
+
/** Compatibility shorthand for structured property writes. */
|
|
652
|
+
properties?: Record<string, unknown | BatchMemorizeRecordProperty>;
|
|
566
653
|
/** Tags for property selection. */
|
|
567
654
|
tags?: string[];
|
|
568
655
|
/** Limit extraction to specific collections. */
|
|
569
656
|
collectionIds?: string[];
|
|
657
|
+
/** Compatibility alias for a single collection name; resolved client-side when possible. */
|
|
658
|
+
collectionName?: string;
|
|
659
|
+
/** Compatibility alias for collectionIds by name; resolved client-side when possible. */
|
|
660
|
+
collectionNames?: string[];
|
|
570
661
|
/** Max properties to select for extraction. */
|
|
571
662
|
max_properties?: number;
|
|
572
663
|
/** If true, extract without persisting (dry run). */
|
|
@@ -575,12 +666,24 @@ export interface MemorizeOptions {
|
|
|
575
666
|
skipDualWrite?: boolean;
|
|
576
667
|
/** If true, skip property selection step. */
|
|
577
668
|
skipPropertySelection?: boolean;
|
|
669
|
+
/** Phone number for entity scoping. */
|
|
670
|
+
phoneNumber?: string;
|
|
671
|
+
/** Postal code for entity scoping. */
|
|
672
|
+
postalCode?: string;
|
|
673
|
+
/** Device ID for entity scoping. */
|
|
674
|
+
deviceId?: string;
|
|
675
|
+
/** Content ID for entity scoping. */
|
|
676
|
+
contentId?: string;
|
|
578
677
|
}
|
|
579
678
|
/** @deprecated Use MemorizeOptions instead. */
|
|
580
679
|
export type MemorizeProOptions = MemorizeOptions;
|
|
581
680
|
export interface SmartRecallOptions {
|
|
582
681
|
/** Natural-language query. */
|
|
583
682
|
query: string;
|
|
683
|
+
/** Compatibility alias for query. */
|
|
684
|
+
message?: string;
|
|
685
|
+
/** Retrieval mode. "fast" skips reflection (~500ms, 1 credit). "deep" enables reflection + answer (~10-20s, 2 credits). Default: "deep". */
|
|
686
|
+
mode?: 'fast' | 'deep';
|
|
584
687
|
/** Max results to return (default: 10). */
|
|
585
688
|
limit?: number;
|
|
586
689
|
/** Minimum similarity score threshold. */
|
|
@@ -597,6 +700,22 @@ export interface SmartRecallOptions {
|
|
|
597
700
|
websiteUrl?: string;
|
|
598
701
|
/** Entity type filter (e.g. 'Contact', 'Company'). */
|
|
599
702
|
type?: string;
|
|
703
|
+
/** Phone number for entity scoping. */
|
|
704
|
+
phoneNumber?: string;
|
|
705
|
+
/** Phone number (snake_case alias). */
|
|
706
|
+
phone_number?: string;
|
|
707
|
+
/** Postal code for entity scoping. */
|
|
708
|
+
postalCode?: string;
|
|
709
|
+
/** Postal code (snake_case alias). */
|
|
710
|
+
postal_code?: string;
|
|
711
|
+
/** Device ID for entity scoping. */
|
|
712
|
+
deviceId?: string;
|
|
713
|
+
/** Device ID (snake_case alias). */
|
|
714
|
+
device_id?: string;
|
|
715
|
+
/** Content ID for entity scoping. */
|
|
716
|
+
contentId?: string;
|
|
717
|
+
/** Content ID (snake_case alias). */
|
|
718
|
+
content_id?: string;
|
|
600
719
|
/** Custom key name — for entity types with domain-specific unique IDs. */
|
|
601
720
|
customKeyName?: string;
|
|
602
721
|
/** Custom key value — the unique identifier value. */
|
|
@@ -605,6 +724,8 @@ export interface SmartRecallOptions {
|
|
|
605
724
|
collectionIds?: string[];
|
|
606
725
|
/** Scope results to specific collections by name (resolved server-side, case-insensitive). */
|
|
607
726
|
collectionNames?: string[];
|
|
727
|
+
/** Compatibility alias for a single collection name. */
|
|
728
|
+
collectionName?: string;
|
|
608
729
|
/** Return schema-enforced property values separately from free-form memories. */
|
|
609
730
|
include_property_values?: boolean;
|
|
610
731
|
/** Enable reflection loop to improve recall coverage (default: true). */
|
|
@@ -629,6 +750,10 @@ export interface SmartRecallOptions {
|
|
|
629
750
|
* In fast_mode, defaults to 10. Set to 0 to disable (strict score cutoff).
|
|
630
751
|
*/
|
|
631
752
|
min_results?: number;
|
|
753
|
+
/** Apply exponential recency decay to scores. Recent memories rank higher. */
|
|
754
|
+
prefer_recent?: boolean;
|
|
755
|
+
/** Half-life in days for recency decay (default: 90). A memory this many days old has its score multiplied by ~0.37. */
|
|
756
|
+
recency_half_life_days?: number;
|
|
632
757
|
/** Metadata filters for narrowing results. */
|
|
633
758
|
filters?: Record<string, unknown>;
|
|
634
759
|
}
|
|
@@ -636,9 +761,13 @@ export interface SmartRecallOptions {
|
|
|
636
761
|
export type RecallProOptions = SmartRecallOptions;
|
|
637
762
|
export interface RecallOptions {
|
|
638
763
|
/** Natural-language query. */
|
|
639
|
-
query
|
|
640
|
-
/**
|
|
641
|
-
|
|
764
|
+
query?: string;
|
|
765
|
+
/** Compatibility alias for query. */
|
|
766
|
+
message?: string;
|
|
767
|
+
/** Entity type (e.g. 'Contact', 'Company'). Required for direct /recall lookups. */
|
|
768
|
+
type?: string;
|
|
769
|
+
/** Compatibility alias retained for older advanced-recall call sites. */
|
|
770
|
+
limit?: number;
|
|
642
771
|
/** CRM record ID for entity scoping. */
|
|
643
772
|
record_id?: string;
|
|
644
773
|
/** CRM record ID (camelCase alias). */
|
|
@@ -653,8 +782,45 @@ export interface RecallOptions {
|
|
|
653
782
|
customKeyName?: string;
|
|
654
783
|
/** Custom key value — the unique identifier value. */
|
|
655
784
|
customKeyValue?: string;
|
|
785
|
+
/** Phone number for entity scoping. */
|
|
786
|
+
phoneNumber?: string;
|
|
787
|
+
/** Postal code for entity scoping. */
|
|
788
|
+
postalCode?: string;
|
|
789
|
+
/** Device ID for entity scoping. */
|
|
790
|
+
deviceId?: string;
|
|
791
|
+
/** Content ID for entity scoping. */
|
|
792
|
+
contentId?: string;
|
|
656
793
|
/** Additional filters. */
|
|
657
794
|
filters?: Record<string, unknown>;
|
|
795
|
+
/** Scope results to specific collections by ID. */
|
|
796
|
+
collectionIds?: string[];
|
|
797
|
+
/** Compatibility alias for a single collection name. */
|
|
798
|
+
collectionName?: string;
|
|
799
|
+
/** Compatibility alias for collection scoping by name. */
|
|
800
|
+
collectionNames?: string[];
|
|
801
|
+
}
|
|
802
|
+
export interface RecallResultItem {
|
|
803
|
+
content?: string;
|
|
804
|
+
memory?: string;
|
|
805
|
+
text?: string;
|
|
806
|
+
createdAt?: string;
|
|
807
|
+
score?: number;
|
|
808
|
+
recordId?: string;
|
|
809
|
+
type?: string;
|
|
810
|
+
email?: string;
|
|
811
|
+
website_url?: string;
|
|
812
|
+
website?: string;
|
|
813
|
+
company_name?: string;
|
|
814
|
+
name?: string;
|
|
815
|
+
properties?: Record<string, PropertyValue>;
|
|
816
|
+
metadata?: Record<string, unknown>;
|
|
817
|
+
[key: string]: unknown;
|
|
818
|
+
}
|
|
819
|
+
export interface RecallResponse extends Array<RecallResultItem> {
|
|
820
|
+
results?: RecallResultItem[];
|
|
821
|
+
answer?: string;
|
|
822
|
+
query?: string;
|
|
823
|
+
[key: string]: unknown;
|
|
658
824
|
}
|
|
659
825
|
export interface BatchMemorizePropertyMapping {
|
|
660
826
|
/** Source field name in the row data */
|
|
@@ -687,17 +853,84 @@ export interface BatchMemorizeMapping {
|
|
|
687
853
|
}
|
|
688
854
|
export interface BatchMemorizeOptions {
|
|
689
855
|
/** Source system label (e.g. 'Hubspot', 'Salesforce') */
|
|
690
|
-
source
|
|
856
|
+
source?: string;
|
|
691
857
|
/** Memorize tier: 'basic' | 'pro' | 'pro_fast' | 'ultra'. Default: 'pro'. */
|
|
692
858
|
tier?: 'basic' | 'pro' | 'pro_fast' | 'ultra';
|
|
693
859
|
/** Mapping configuration for the sync */
|
|
694
|
-
mapping
|
|
860
|
+
mapping?: BatchMemorizeMapping;
|
|
695
861
|
/** Array of source data rows (key-value objects matching sourceField names) */
|
|
696
|
-
rows
|
|
862
|
+
rows?: Record<string, unknown>[];
|
|
697
863
|
/** If true, validate without writing (default: false) */
|
|
698
864
|
dryRun?: boolean;
|
|
699
865
|
/** Number of rows to process per chunk (default: 1) */
|
|
700
866
|
chunkSize?: number;
|
|
867
|
+
/** Compatibility flag accepted and ignored when not needed. */
|
|
868
|
+
enhanced?: boolean;
|
|
869
|
+
/** Compatibility shorthand accepted by the SDK and normalized client-side. */
|
|
870
|
+
records?: BatchMemorizeRecord[];
|
|
871
|
+
}
|
|
872
|
+
export interface BatchMemorizeRecordProperty {
|
|
873
|
+
value: unknown;
|
|
874
|
+
extractMemories?: boolean;
|
|
875
|
+
collectionId?: string;
|
|
876
|
+
collectionName?: string;
|
|
877
|
+
}
|
|
878
|
+
export interface BatchMemorizeRecord {
|
|
879
|
+
content?: string;
|
|
880
|
+
email?: string;
|
|
881
|
+
website_url?: string;
|
|
882
|
+
websiteUrl?: string;
|
|
883
|
+
record_id?: string;
|
|
884
|
+
recordId?: string;
|
|
885
|
+
type?: string;
|
|
886
|
+
customKeyName?: string;
|
|
887
|
+
customKeyValue?: string;
|
|
888
|
+
collectionId?: string;
|
|
889
|
+
collectionName?: string;
|
|
890
|
+
properties?: Record<string, unknown | BatchMemorizeRecordProperty>;
|
|
891
|
+
tags?: string[];
|
|
892
|
+
enhanced?: boolean;
|
|
893
|
+
timestamp?: string;
|
|
894
|
+
speaker?: string;
|
|
895
|
+
}
|
|
896
|
+
export interface GetPropertiesOptions {
|
|
897
|
+
/** Contact email. */
|
|
898
|
+
email?: string;
|
|
899
|
+
/** Company website URL. */
|
|
900
|
+
websiteUrl?: string;
|
|
901
|
+
/** Website URL (snake_case alias). */
|
|
902
|
+
website_url?: string;
|
|
903
|
+
/** CRM record ID. */
|
|
904
|
+
recordId?: string;
|
|
905
|
+
/** CRM record ID (snake_case alias). */
|
|
906
|
+
record_id?: string;
|
|
907
|
+
/** Entity type. */
|
|
908
|
+
type?: string;
|
|
909
|
+
/** Custom CRM key field name. */
|
|
910
|
+
customKeyName?: string;
|
|
911
|
+
/** Custom CRM key field value. */
|
|
912
|
+
customKeyValue?: string;
|
|
913
|
+
/** Filter to specific properties by name. */
|
|
914
|
+
propertyNames?: string[];
|
|
915
|
+
/** Include collection schema descriptions (default: true). */
|
|
916
|
+
includeDescriptions?: boolean;
|
|
917
|
+
/** Only return non-empty properties (default: false). */
|
|
918
|
+
nonEmpty?: boolean;
|
|
919
|
+
}
|
|
920
|
+
export interface PropertyItem {
|
|
921
|
+
name: string;
|
|
922
|
+
value: unknown;
|
|
923
|
+
type?: string;
|
|
924
|
+
description?: string;
|
|
925
|
+
/** true = replaceable (set), false = append-only (push only). */
|
|
926
|
+
update?: boolean;
|
|
927
|
+
collectionId?: string;
|
|
928
|
+
collectionName?: string;
|
|
929
|
+
}
|
|
930
|
+
export interface GetPropertiesResponse {
|
|
931
|
+
recordId: string;
|
|
932
|
+
type: string;
|
|
933
|
+
properties: PropertyItem[];
|
|
701
934
|
}
|
|
702
935
|
export interface SmartDigestOptions {
|
|
703
936
|
/** CRM record ID */
|
|
@@ -728,6 +961,14 @@ export interface SmartDigestOptions {
|
|
|
728
961
|
include_memories?: boolean;
|
|
729
962
|
/** Include memories (camelCase alias). */
|
|
730
963
|
includeMemories?: boolean;
|
|
964
|
+
/** Phone number for entity scoping. */
|
|
965
|
+
phoneNumber?: string;
|
|
966
|
+
/** Postal code for entity scoping. */
|
|
967
|
+
postalCode?: string;
|
|
968
|
+
/** Device ID for entity scoping. */
|
|
969
|
+
deviceId?: string;
|
|
970
|
+
/** Content ID for entity scoping. */
|
|
971
|
+
contentId?: string;
|
|
731
972
|
}
|
|
732
973
|
export interface SmartDigestResponse {
|
|
733
974
|
success: boolean;
|
|
@@ -758,6 +999,8 @@ export interface SearchFilterGroup {
|
|
|
758
999
|
conditions: SearchFilterCondition[];
|
|
759
1000
|
}
|
|
760
1001
|
export interface SearchOptions {
|
|
1002
|
+
/** Compatibility shorthand for semantic search; routed client-side to smartRecall when groups are omitted. */
|
|
1003
|
+
query?: string;
|
|
761
1004
|
/** Filter groups with conditions. To list all records, send one group with empty conditions. */
|
|
762
1005
|
groups?: SearchFilterGroup[];
|
|
763
1006
|
/** Entity type (e.g. 'Contact', 'Company'). */
|
|
@@ -768,12 +1011,22 @@ export interface SearchOptions {
|
|
|
768
1011
|
websiteUrl?: string;
|
|
769
1012
|
/** Scope to a specific record ID. */
|
|
770
1013
|
recordId?: string;
|
|
1014
|
+
/** Custom key name for custom entity types (e.g. 'studentNumber', 'linkedinUrl'). */
|
|
1015
|
+
customKeyName?: string;
|
|
1016
|
+
/** Custom key value (e.g. 'S-2024-1234'). Used with customKeyName to scope to a custom-keyed record. */
|
|
1017
|
+
customKeyValue?: string;
|
|
771
1018
|
/** Scope to specific collections. */
|
|
772
1019
|
collectionIds?: string[];
|
|
1020
|
+
/** Compatibility alias for a single collection name. */
|
|
1021
|
+
collectionName?: string;
|
|
1022
|
+
/** Compatibility alias for collection scoping by name. */
|
|
1023
|
+
collectionNames?: string[];
|
|
773
1024
|
/** Page number (1-based, default: 1). */
|
|
774
1025
|
page?: number;
|
|
775
1026
|
/** Results per page (max 200, default: 50). */
|
|
776
1027
|
pageSize?: number;
|
|
1028
|
+
/** Compatibility alias for pageSize. */
|
|
1029
|
+
limit?: number;
|
|
777
1030
|
/** Return only totalMatched count. */
|
|
778
1031
|
countOnly?: boolean;
|
|
779
1032
|
/** Include property values per record. */
|
|
@@ -782,6 +1035,8 @@ export interface SearchOptions {
|
|
|
782
1035
|
includeMemories?: boolean;
|
|
783
1036
|
/** Data source: 'lancedb' or 'snapshot' (default: 'lancedb'). */
|
|
784
1037
|
dataSource?: 'lancedb' | 'snapshot';
|
|
1038
|
+
/** Compatibility shorthand filters; converted client-side to groups where possible. */
|
|
1039
|
+
filters?: Record<string, unknown>;
|
|
785
1040
|
}
|
|
786
1041
|
/** @deprecated Use SearchOptions instead. */
|
|
787
1042
|
export type ExportOptions = SearchOptions;
|
|
@@ -791,7 +1046,30 @@ export interface MemoryItem {
|
|
|
791
1046
|
score?: number;
|
|
792
1047
|
metadata?: Record<string, PropertyValue>;
|
|
793
1048
|
}
|
|
794
|
-
export interface
|
|
1049
|
+
export interface SearchResultItem {
|
|
1050
|
+
recordId?: string;
|
|
1051
|
+
mainProperties?: Record<string, string>;
|
|
1052
|
+
record?: Record<string, {
|
|
1053
|
+
value: PropertyValue;
|
|
1054
|
+
collectionId: string;
|
|
1055
|
+
collectionName?: string;
|
|
1056
|
+
}>;
|
|
1057
|
+
memories?: MemoryItem[];
|
|
1058
|
+
content?: string;
|
|
1059
|
+
memory?: string;
|
|
1060
|
+
email?: string;
|
|
1061
|
+
website_url?: string;
|
|
1062
|
+
website?: string;
|
|
1063
|
+
company_name?: string;
|
|
1064
|
+
name?: string;
|
|
1065
|
+
linkedin_url?: string;
|
|
1066
|
+
phone_number?: string;
|
|
1067
|
+
crm_id?: string;
|
|
1068
|
+
lead_score?: number;
|
|
1069
|
+
properties?: Record<string, PropertyValue>;
|
|
1070
|
+
[key: string]: unknown;
|
|
1071
|
+
}
|
|
1072
|
+
export interface SearchResponse extends Array<SearchResultItem> {
|
|
795
1073
|
recordIds: string[];
|
|
796
1074
|
totalMatched: number;
|
|
797
1075
|
page: number;
|
|
@@ -807,9 +1085,228 @@ export interface SearchResponse {
|
|
|
807
1085
|
mainProperties?: Record<string, Record<string, string>>;
|
|
808
1086
|
/** Free-form memories per record (when includeMemories is true). */
|
|
809
1087
|
memories?: Record<string, MemoryItem[]>;
|
|
1088
|
+
/** Compatibility flattened result list derived client-side when possible. */
|
|
1089
|
+
results?: SearchResultItem[];
|
|
810
1090
|
}
|
|
811
1091
|
/** @deprecated Use SearchResponse instead. */
|
|
812
1092
|
export type ExportResponse = SearchResponse;
|
|
1093
|
+
export interface UpdatePropertyOptions {
|
|
1094
|
+
/** Target record ID. */
|
|
1095
|
+
recordId: string;
|
|
1096
|
+
/** Entity type (default: 'contact'). */
|
|
1097
|
+
type?: string;
|
|
1098
|
+
/** Property to update. Required for property updates (mutually exclusive with memoryId+text). */
|
|
1099
|
+
propertyName?: string;
|
|
1100
|
+
/** New property value. Required unless using array operations. */
|
|
1101
|
+
propertyValue?: any;
|
|
1102
|
+
/** Collection ID for the property. */
|
|
1103
|
+
collectionId?: string;
|
|
1104
|
+
/** Confidence score for this value. */
|
|
1105
|
+
confidence?: number;
|
|
1106
|
+
/** Reason for the change (logged in property history). */
|
|
1107
|
+
reason?: string;
|
|
1108
|
+
/** Who made the change (auto-set from API key if omitted). */
|
|
1109
|
+
updatedBy?: string;
|
|
1110
|
+
/** Idempotency key to prevent duplicate writes. */
|
|
1111
|
+
idempotencyKey?: string;
|
|
1112
|
+
/** Optimistic concurrency guard. If set, returns 409 if the record's current version differs. */
|
|
1113
|
+
expectedVersion?: number;
|
|
1114
|
+
/** Append items to an array property. With `unique: true`, skips duplicates. */
|
|
1115
|
+
arrayPush?: {
|
|
1116
|
+
items: any[];
|
|
1117
|
+
unique?: boolean;
|
|
1118
|
+
};
|
|
1119
|
+
/** Remove items from an array property by value or index. */
|
|
1120
|
+
arrayRemove?: {
|
|
1121
|
+
items?: any[];
|
|
1122
|
+
indices?: number[];
|
|
1123
|
+
};
|
|
1124
|
+
/** Update matching objects inside an array property. */
|
|
1125
|
+
arrayPatch?: {
|
|
1126
|
+
match: Record<string, any>;
|
|
1127
|
+
set: Record<string, any>;
|
|
1128
|
+
};
|
|
1129
|
+
/** Freeform memory UUID to edit. */
|
|
1130
|
+
memoryId?: string;
|
|
1131
|
+
/** New text for the freeform memory. */
|
|
1132
|
+
text?: string;
|
|
1133
|
+
}
|
|
1134
|
+
export interface UpdateResult {
|
|
1135
|
+
success: boolean;
|
|
1136
|
+
previousValue?: any;
|
|
1137
|
+
newValue: any;
|
|
1138
|
+
version?: number;
|
|
1139
|
+
stores: {
|
|
1140
|
+
snapshot: 'updated' | 'skipped';
|
|
1141
|
+
lancedb: 'updated' | 'skipped';
|
|
1142
|
+
freeform: 'updated' | 'skipped';
|
|
1143
|
+
};
|
|
1144
|
+
}
|
|
1145
|
+
export interface BulkUpdateOptions {
|
|
1146
|
+
/** Target record ID. */
|
|
1147
|
+
recordId: string;
|
|
1148
|
+
/** Entity type (default: 'contact'). */
|
|
1149
|
+
type?: string;
|
|
1150
|
+
/** Array of property updates. */
|
|
1151
|
+
updates: Array<{
|
|
1152
|
+
propertyName: string;
|
|
1153
|
+
propertyValue: any;
|
|
1154
|
+
collectionId?: string;
|
|
1155
|
+
confidence?: number;
|
|
1156
|
+
}>;
|
|
1157
|
+
/** Who made the changes. */
|
|
1158
|
+
updatedBy?: string;
|
|
1159
|
+
/** Idempotency key to prevent duplicate writes. */
|
|
1160
|
+
idempotencyKey?: string;
|
|
1161
|
+
/** Optimistic concurrency guard. Checked before any writes; 409 if mismatch. */
|
|
1162
|
+
expectedVersion?: number;
|
|
1163
|
+
}
|
|
1164
|
+
export interface BulkUpdateResult {
|
|
1165
|
+
success: boolean;
|
|
1166
|
+
results: Array<{
|
|
1167
|
+
propertyName: string;
|
|
1168
|
+
previousValue?: any;
|
|
1169
|
+
newValue: any;
|
|
1170
|
+
status: 'updated' | 'failed';
|
|
1171
|
+
error?: string;
|
|
1172
|
+
}>;
|
|
1173
|
+
version?: number;
|
|
1174
|
+
}
|
|
1175
|
+
export interface PropertyHistoryOptions {
|
|
1176
|
+
/** Target record ID. */
|
|
1177
|
+
recordId: string;
|
|
1178
|
+
/** Filter to a specific property. */
|
|
1179
|
+
propertyName?: string;
|
|
1180
|
+
/** ISO-8601 lower bound. */
|
|
1181
|
+
from?: string;
|
|
1182
|
+
/** ISO-8601 upper bound. */
|
|
1183
|
+
to?: string;
|
|
1184
|
+
/** Max entries to return (default: 50, max: 200). */
|
|
1185
|
+
limit?: number;
|
|
1186
|
+
/** Pagination cursor from previous response. */
|
|
1187
|
+
nextToken?: string;
|
|
1188
|
+
}
|
|
1189
|
+
export interface PropertyHistoryEntry {
|
|
1190
|
+
entryId: string;
|
|
1191
|
+
propertyName: string;
|
|
1192
|
+
propertyValue: any;
|
|
1193
|
+
collectionId: string;
|
|
1194
|
+
collectionName?: string;
|
|
1195
|
+
updatedBy: string;
|
|
1196
|
+
createdAt: string;
|
|
1197
|
+
source?: string;
|
|
1198
|
+
}
|
|
1199
|
+
export interface PropertyHistoryResult {
|
|
1200
|
+
entries: PropertyHistoryEntry[];
|
|
1201
|
+
nextToken?: string;
|
|
1202
|
+
}
|
|
1203
|
+
export interface QueryPropertiesOptions {
|
|
1204
|
+
/** Which property to search across. */
|
|
1205
|
+
propertyName: string;
|
|
1206
|
+
/** Natural language query. */
|
|
1207
|
+
query: string;
|
|
1208
|
+
/** Limit to single record. */
|
|
1209
|
+
recordId?: string;
|
|
1210
|
+
/** Entity type filter (default: 'contact'). */
|
|
1211
|
+
type?: string;
|
|
1212
|
+
/** Max results (default: 100, max: 200). */
|
|
1213
|
+
limit?: number;
|
|
1214
|
+
}
|
|
1215
|
+
export interface QueryPropertiesResult {
|
|
1216
|
+
matches: Array<{
|
|
1217
|
+
recordId: string;
|
|
1218
|
+
propertyValue: any;
|
|
1219
|
+
matchReason: string;
|
|
1220
|
+
}>;
|
|
1221
|
+
processedCount: number;
|
|
1222
|
+
totalAvailable: number;
|
|
1223
|
+
truncated: boolean;
|
|
1224
|
+
capMessage?: string;
|
|
1225
|
+
}
|
|
1226
|
+
export interface DeleteMemoriesOptions {
|
|
1227
|
+
/** Memory UUIDs to delete. */
|
|
1228
|
+
ids?: string[];
|
|
1229
|
+
/** CRM identifiers for scoping. */
|
|
1230
|
+
crmKeys?: {
|
|
1231
|
+
recordId?: string;
|
|
1232
|
+
email?: string;
|
|
1233
|
+
websiteUrl?: string;
|
|
1234
|
+
};
|
|
1235
|
+
/** ISO date — delete memories older than this. */
|
|
1236
|
+
olderThan?: string;
|
|
1237
|
+
}
|
|
1238
|
+
export interface DeleteRecordOptions {
|
|
1239
|
+
/** Record ID to delete. */
|
|
1240
|
+
recordId: string;
|
|
1241
|
+
/** Entity type (required). */
|
|
1242
|
+
type: string;
|
|
1243
|
+
/** CRM identifiers for additional LanceDB filtering. */
|
|
1244
|
+
crmKeys?: {
|
|
1245
|
+
recordId?: string;
|
|
1246
|
+
email?: string;
|
|
1247
|
+
websiteUrl?: string;
|
|
1248
|
+
};
|
|
1249
|
+
/** Reason for deletion. */
|
|
1250
|
+
reason?: string;
|
|
1251
|
+
/** Who performed the deletion. */
|
|
1252
|
+
performedBy?: string;
|
|
1253
|
+
}
|
|
1254
|
+
export interface DeletionResult {
|
|
1255
|
+
success: boolean;
|
|
1256
|
+
deletedCount?: number;
|
|
1257
|
+
hardDeleteAt?: string;
|
|
1258
|
+
}
|
|
1259
|
+
export interface CancelDeletionOptions {
|
|
1260
|
+
/** Record ID to restore. */
|
|
1261
|
+
recordId: string;
|
|
1262
|
+
/** Entity type (default: 'contact'). */
|
|
1263
|
+
type?: string;
|
|
1264
|
+
/** Who performed the restoration. */
|
|
1265
|
+
performedBy?: string;
|
|
1266
|
+
}
|
|
1267
|
+
export interface CancelDeletionResult {
|
|
1268
|
+
success: boolean;
|
|
1269
|
+
restoredCounts: {
|
|
1270
|
+
snapshot: 'restored' | 'already_gone';
|
|
1271
|
+
freeform: 'restored' | 'already_gone';
|
|
1272
|
+
lancedb: 'restored' | 'already_gone';
|
|
1273
|
+
};
|
|
1274
|
+
warning?: string;
|
|
1275
|
+
}
|
|
1276
|
+
/** Comparison operators for deterministic property filters. */
|
|
1277
|
+
export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' | 'isEmpty';
|
|
1278
|
+
export interface PropertyFilterCondition {
|
|
1279
|
+
/** Property to filter on. */
|
|
1280
|
+
propertyName: string;
|
|
1281
|
+
/** Comparison operator. */
|
|
1282
|
+
operator: FilterOperator;
|
|
1283
|
+
/** Value to compare against. Not needed for 'exists'/'isEmpty'. */
|
|
1284
|
+
value?: any;
|
|
1285
|
+
}
|
|
1286
|
+
export interface FilterByPropertyOptions {
|
|
1287
|
+
/** Entity type (default: 'contact'). */
|
|
1288
|
+
type?: string;
|
|
1289
|
+
/** Filter conditions. */
|
|
1290
|
+
conditions: PropertyFilterCondition[];
|
|
1291
|
+
/** Combine conditions with AND (default) or OR. */
|
|
1292
|
+
logic?: 'AND' | 'OR';
|
|
1293
|
+
/** Max results (default: 50, max: 200). */
|
|
1294
|
+
limit?: number;
|
|
1295
|
+
/** Pagination cursor. */
|
|
1296
|
+
nextToken?: string;
|
|
1297
|
+
}
|
|
1298
|
+
export interface FilterByPropertyResult {
|
|
1299
|
+
records: Array<{
|
|
1300
|
+
recordId: string;
|
|
1301
|
+
type: string;
|
|
1302
|
+
matchedProperties: Record<string, any>;
|
|
1303
|
+
lastUpdatedAt?: number;
|
|
1304
|
+
}>;
|
|
1305
|
+
totalMatched: number;
|
|
1306
|
+
nextToken?: string;
|
|
1307
|
+
}
|
|
1308
|
+
/** Webhook event types fired by memory CRUD operations. */
|
|
1309
|
+
export type MemoryWebhookEvent = 'memory.property.updated' | 'memory.properties.bulk_updated' | 'memory.updated' | 'memory.deleted' | 'memory.record.deleted' | 'memory.record.deletion_cancelled';
|
|
813
1310
|
export interface EvaluateMemorizationOptions {
|
|
814
1311
|
/** Collection to evaluate against. */
|
|
815
1312
|
collectionId: string;
|