@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/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 GuidelinesResponse {
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 CollectionsResponse {
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: string;
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: string;
640
- /** Entity type (e.g. 'Contact', 'Company'). Required by the /recall endpoint. */
641
- type: string;
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: string;
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: BatchMemorizeMapping;
860
+ mapping?: BatchMemorizeMapping;
695
861
  /** Array of source data rows (key-value objects matching sourceField names) */
696
- rows: Record<string, unknown>[];
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 SearchResponse {
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;