@personize/sdk 0.7.3 → 0.7.4

package/README.md

@@ -541,22 +541,45 @@ const result = await client.agents.run(agentId, {
 
 ### Collections
 
+Collections define the property schemas that the AI extraction pipeline uses when memorizing content.
+
 ```typescript
 // List collections
 const collections = await client.collections.list();
 
-// Create a collection
+// Create a collection with properties
 await client.collections.create({
-    collectionName: 'Deal Properties',
+    collectionName: 'Contact Properties',
     entityType: 'Contact',
+    definition: 'Customer profile fields for GTM workflows',
+    properties: [
+        { propertyName: 'Lifecycle Stage', type: 'options', options: 'Lead, MQL, SQL, Customer', description: 'Current funnel stage', update: true },
+        { propertyName: 'Meeting Notes', type: 'array', description: 'Chronological meeting log', update: false, tags: ['interaction'] },
+    ],
+});
+
+// Add a single property to an existing collection (incremental -- existing properties are preserved)
+await client.collections.update(collectionId, {
+    properties: [
+        { propertyName: 'Location', type: 'text', description: 'City or region', update: true, tags: ['identity'] },
+    ],
+    historyNote: 'Added Location property',
+});
+
+// Add multiple properties at once
+await client.collections.update(collectionId, {
     properties: [
-        { propertyName: 'Deal Stage', type: 'options', options: 'Discovery,Proposal,Closed' },
+        { propertyName: 'Budget Range', type: 'options', options: '<50K, 50K-200K, 200K-1M, >1M', update: true },
+        { propertyName: 'Decision Timeline', type: 'text', description: 'When they plan to buy', update: true },
+        { propertyName: 'Objections Log', type: 'array', description: 'Sales objections raised', update: false },
     ],
+    historyNote: 'Added qualification properties for lead scoring',
 });
 
-// Update a collection
+// Soft-delete a property (existing stored values are preserved)
 await client.collections.update(collectionId, {
-    properties: [{ propertyName: 'Budget', type: 'number', description: 'Estimated budget' }],
+    properties: [{ propertyName: 'Old Field', systemName: 'old_field', status: 'Deleted' }],
+    historyNote: 'Retired Old Field property',
 });
 
 // Delete a collection
@@ -566,6 +589,24 @@ await client.collections.delete(collectionId);
 const history = await client.collections.history(collectionId, { mode: 'diff', limit: 10 });
 ```
 
+**Property definition fields:** `propertyName` (required), `systemName` (auto-generated), `type` (`'text'` | `'number'` | `'boolean'` | `'array'` | `'date'` | `'options'`, default `'text'`), `description`, `update` (`true` = replaceable, `false` = append-only), `options`, `tags`, `status` (`'Active'` | `'Deleted'`).
+
+See `CollectionPropertyDefinition` in `types.ts` for the full reference.
+
+### Defaults & Limits
+
+Default result sizes for retrieval methods. All are optional -- pass explicitly to request more or fewer.
+
+| Method | Param | Default | Max | Notes |
+|--------|-------|---------|-----|-------|
+| `memory.smartRecall()` | `token_budget` | 4,000 tokens | -- | Token-budgeted, not count-based |
+| `memory.recall()` | `limit` | 10 memories | 5,000 | |
+| `memory.smartDigest()` | `token_budget` | 1,000 tokens | -- | Also accepts `maxMemories` (default 20) |
+| `memory.search()` / `memory.filterByProperty()` | `pageSize` | 50 records | 200 | |
+| `memory.similar()` | `topK` | 25 records | 5,000 | |
+| `memory.segment()` | `maxPerTier` | 50 per tier | -- | No hard cap |
+| `memory.memorize()` (batch) | items | -- | 100 | Optimal: 10-50 per call |
+
 ### Evaluation
 
 ```typescript

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, PromptStreamOptions, PromptSSEEvent, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, RecallResponse, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse, UpdatePropertyOptions, UpdateResult, BulkUpdateOptions, BulkUpdateResult, PropertyHistoryOptions, PropertyHistoryResult, QueryPropertiesOptions, QueryPropertiesResult, DeleteMemoriesOptions, DeleteRecordOptions, DeletionResult, CancelDeletionOptions, CancelDeletionResult, FilterByPropertyOptions, FilterByPropertyResult, GetPropertiesOptions, GetPropertiesResponse, ResponsesCreateOptions, ResponsesCompletedResult, ChatCompletionsOptions, ChatCompletionResult, SimilarOptions, SimilarResponse, SegmentOptions, SegmentResponse } from './types';
+import { PersonizeConfig, ApiResponse, MeResponse, TestResponse, ListOptions, GuidelinesResponse, GuidelineSectionOptions, GuidelineUpdatePayload, GuidelineCreatePayload, GuidelineHistoryResponse, GuidelineHistoryOptions, CollectionsResponse, CollectionCreatePayload, CollectionUpdatePayload, CollectionHistoryOptions, CollectionHistoryResponse, SmartGuidelinesOptions, SmartGuidelinesResponse, PromptOptions, PromptResponse, PromptStreamOptions, PromptSSEEvent, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, RecallResponse, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse, UpdatePropertyOptions, UpdateResult, BulkUpdateOptions, BulkUpdateResult, PropertyHistoryOptions, PropertyHistoryResult, QueryPropertiesOptions, QueryPropertiesResult, DeleteMemoriesOptions, DeleteRecordOptions, DeletionResult, CancelDeletionOptions, CancelDeletionResult, FilterByPropertyOptions, FilterByPropertyResult, GetPropertiesOptions, GetPropertiesResponse, ResponsesCreateOptions, ResponsesCompletedResult, ChatCompletionsOptions, ChatCompletionResult, SimilarOptions, SimilarResponse, SegmentOptions, SegmentResponse, UpdateKeysOptions, UpdateKeysResponse, UpdateKeysBatchOptions, UpdateKeysBatchResponse, ListKeysOptions, ListKeysResponse, DeleteKeysOptions, DeleteKeysResponse, SmartUpdateOptions, SmartUpdateResponse, GovernanceAttachment, AttachmentUpdateOptions, AttachmentUploadOptions, BatchAttachmentUploadOptions } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -68,6 +68,48 @@ export declare class Personize {
          * GET /api/v1/actions/:id/history — Get version history for a guideline
          */
         history: (id: string, options?: GuidelineHistoryOptions) => Promise<ApiResponse<GuidelineHistoryResponse>>;
+        /**
+         * POST /api/v1/smart-update -- AI-powered governance & schema evolution.
+         * Analyzes instruction + material against existing guidelines or collections
+         * and returns (or applies) a structured change plan.
+         */
+        smartUpdate: (data: SmartUpdateOptions) => Promise<ApiResponse<SmartUpdateResponse>>;
+        /**
+         * GET /api/v1/guidelines/:guidelineId/attachments — List all attachments for a guideline.
+         */
+        listAttachments: (guidelineId: string) => Promise<ApiResponse<GovernanceAttachment[]>>;
+        /**
+         * GET /api/v1/guidelines/:guidelineId/attachments/:attachmentId — Get attachment metadata and a signed download URL.
+         */
+        getAttachment: (guidelineId: string, attachmentId: string) => Promise<ApiResponse<GovernanceAttachment & {
+            downloadUrl: string;
+        }>>;
+        /**
+         * PATCH /api/v1/guidelines/:guidelineId/attachments/:attachmentId — Update attachment metadata (description, usage, type, language, sectionHeader).
+         */
+        updateAttachment: (guidelineId: string, attachmentId: string, options: AttachmentUpdateOptions) => Promise<ApiResponse<GovernanceAttachment>>;
+        /**
+         * DELETE /api/v1/guidelines/:guidelineId/attachments/:attachmentId — Delete an attachment.
+         */
+        deleteAttachment: (guidelineId: string, attachmentId: string) => Promise<ApiResponse<void>>;
+        /**
+         * POST /api/v1/guidelines/:guidelineId/attachments — Upload a new attachment.
+         * @todo Requires multipart/form-data support (postFormData). Not yet implemented.
+         */
+        uploadAttachment: (_guidelineId: string, _options: AttachmentUploadOptions) => Promise<ApiResponse<GovernanceAttachment>>;
+        /**
+         * PUT /api/v1/guidelines/:guidelineId/attachments/:attachmentId/content — Replace attachment file content.
+         * @todo Requires multipart/form-data support (postFormData). Not yet implemented.
+         */
+        replaceAttachmentContent: (_guidelineId: string, _attachmentId: string, _file: Buffer) => Promise<ApiResponse<GovernanceAttachment>>;
+        /**
+         * POST /api/v1/guidelines/:guidelineId/attachments/batch — Upload multiple attachments in one request.
+         * @todo Requires multipart/form-data support (postFormData). Not yet implemented.
+         */
+        batchUploadAttachments: (_guidelineId: string, _options: BatchAttachmentUploadOptions) => Promise<ApiResponse<{
+            uploaded: GovernanceAttachment[];
+            warnings: string[];
+        }>>;
     };
     collections: {
         /**
@@ -243,6 +285,25 @@ export declare class Personize {
          * @see https://docs.personize.ai/api#segment
          */
         segment: (data: SegmentOptions) => Promise<ApiResponse<SegmentResponse>>;
+        /**
+         * POST /api/v1/memory/update-keys -- Add keys (standard or custom) to a record.
+         * Identify the record by recordId, email, websiteUrl, or any CRM key.
+         */
+        updateKeys: (data: UpdateKeysOptions) => Promise<ApiResponse<UpdateKeysResponse>>;
+        /**
+         * POST /api/v1/memory/update-keys-batch -- Add keys across multiple records.
+         * Max 100 records, 50 keys per record.
+         */
+        updateKeysBatch: (data: UpdateKeysBatchOptions) => Promise<ApiResponse<UpdateKeysBatchResponse>>;
+        /**
+         * POST /api/v1/memory/list-keys -- List all keys (standard + custom) on a record.
+         */
+        listKeys: (data: ListKeysOptions) => Promise<ApiResponse<ListKeysResponse>>;
+        /**
+         * POST /api/v1/memory/delete-keys -- Delete specific key aliases from a record.
+         * Blocks deletion if it would leave zero aliases.
+         */
+        deleteKeys: (data: DeleteKeysOptions) => Promise<ApiResponse<DeleteKeysResponse>>;
     };
     smartRecallUnified: (data: import("./types").SmartRecallUnifiedOptions) => Promise<import("./types").ApiResponse<import("./types").SmartRecallUnifiedResponse>>;
     rag: {
@@ -256,6 +317,29 @@ export declare class Personize {
             healthy: boolean;
             latencyMs: number;
         }>>;
+        /** Our LanceDB RAG: ingest documents into a project */
+        ingest: (data: import("./types").RAGIngestOptions) => Promise<import("./types").ApiResponse<{
+            ingested: number;
+            errors: string[];
+        }>>;
+        /** Our LanceDB RAG: search a project */
+        searchProject: (data: import("./types").RAGSearchOptions) => Promise<import("./types").ApiResponse<{
+            results: import("./types").RAGSearchResult[];
+            count: number;
+        }>>;
+        /** Our LanceDB RAG: list projects for this org */
+        listProjects: () => Promise<import("./types").ApiResponse<{
+            projects: string[];
+            count: number;
+        }>>;
+        /** Our LanceDB RAG: delete documents from a project */
+        deleteDocuments: (data: import("./types").RAGDeleteOptions) => Promise<import("./types").ApiResponse<{
+            deleted: number;
+        }>>;
+        /** Our LanceDB RAG: delete an entire project */
+        deleteProject: (projectId: string) => Promise<import("./types").ApiResponse<{
+            message: string;
+        }>>;
     };
     multimodal: {
         memorize: (data: import("./types").MultimodalMemorizeOptions) => Promise<import("./types").ApiResponse<{

package/dist/client.js

@@ -85,6 +85,77 @@ class Personize {
                 });
                 return response.data;
             },
+            /**
+             * POST /api/v1/smart-update -- AI-powered governance & schema evolution.
+             * Analyzes instruction + material against existing guidelines or collections
+             * and returns (or applies) a structured change plan.
+             */
+            smartUpdate: async (data) => {
+                const payload = {
+                    type: data.type,
+                    instruction: data.instruction,
+                    material: data.material,
+                    strategy: data.strategy || 'suggest',
+                };
+                if (data.targetIds || data.target_ids) {
+                    payload.targetIds = data.targetIds || data.target_ids;
+                }
+                const response = await this.client.post('/api/v1/smart-update', payload);
+                return response.data;
+            },
+            // ── Attachment methods ────────────────────────────────────────────────
+            /**
+             * GET /api/v1/guidelines/:guidelineId/attachments — List all attachments for a guideline.
+             */
+            listAttachments: async (guidelineId) => {
+                const response = await this.client.get(`/api/v1/guidelines/${guidelineId}/attachments`);
+                return response.data;
+            },
+            /**
+             * GET /api/v1/guidelines/:guidelineId/attachments/:attachmentId — Get attachment metadata and a signed download URL.
+             */
+            getAttachment: async (guidelineId, attachmentId) => {
+                const response = await this.client.get(`/api/v1/guidelines/${guidelineId}/attachments/${attachmentId}`);
+                return response.data;
+            },
+            /**
+             * PATCH /api/v1/guidelines/:guidelineId/attachments/:attachmentId — Update attachment metadata (description, usage, type, language, sectionHeader).
+             */
+            updateAttachment: async (guidelineId, attachmentId, options) => {
+                const response = await this.client.patch(`/api/v1/guidelines/${guidelineId}/attachments/${attachmentId}`, options);
+                return response.data;
+            },
+            /**
+             * DELETE /api/v1/guidelines/:guidelineId/attachments/:attachmentId — Delete an attachment.
+             */
+            deleteAttachment: async (guidelineId, attachmentId) => {
+                const response = await this.client.delete(`/api/v1/guidelines/${guidelineId}/attachments/${attachmentId}`);
+                return response.data;
+            },
+            // TODO: The following attachment methods require multipart/form-data upload support,
+            // which the SDK HTTP client does not currently implement. Add postFormData() to the
+            // Axios instance wrapper and then implement these methods.
+            /**
+             * POST /api/v1/guidelines/:guidelineId/attachments — Upload a new attachment.
+             * @todo Requires multipart/form-data support (postFormData). Not yet implemented.
+             */
+            uploadAttachment: async (_guidelineId, _options) => {
+                throw new Error('uploadAttachment requires multipart/form-data support, which is not yet implemented in the SDK HTTP layer. Add postFormData() to the client and reimplement this method.');
+            },
+            /**
+             * PUT /api/v1/guidelines/:guidelineId/attachments/:attachmentId/content — Replace attachment file content.
+             * @todo Requires multipart/form-data support (postFormData). Not yet implemented.
+             */
+            replaceAttachmentContent: async (_guidelineId, _attachmentId, _file) => {
+                throw new Error('replaceAttachmentContent requires multipart/form-data support, which is not yet implemented in the SDK HTTP layer. Add postFormData() to the client and reimplement this method.');
+            },
+            /**
+             * POST /api/v1/guidelines/:guidelineId/attachments/batch — Upload multiple attachments in one request.
+             * @todo Requires multipart/form-data support (postFormData). Not yet implemented.
+             */
+            batchUploadAttachments: async (_guidelineId, _options) => {
+                throw new Error('batchUploadAttachments requires multipart/form-data support, which is not yet implemented in the SDK HTTP layer. Add postFormData() to the client and reimplement this method.');
+            },
         };
         this.collections = {
             /**
@@ -249,6 +320,7 @@ class Personize {
                     return this.memorizeBatchFromRecords({
                         source: 'SDK memorize compatibility',
                         enhanced: data.enhanced,
+                        extractionPrompt: data.extractionPrompt,
                         records: [{
                                 content: data.content,
                                 email: data.email,
@@ -474,6 +546,37 @@ class Personize {
                 const response = await this.client.post('/api/v1/segment', data);
                 return response.data;
             },
+            /**
+             * POST /api/v1/memory/update-keys -- Add keys (standard or custom) to a record.
+             * Identify the record by recordId, email, websiteUrl, or any CRM key.
+             */
+            updateKeys: async (data) => {
+                const response = await this.client.post('/api/v1/memory/update-keys', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/update-keys-batch -- Add keys across multiple records.
+             * Max 100 records, 50 keys per record.
+             */
+            updateKeysBatch: async (data) => {
+                const response = await this.client.post('/api/v1/memory/update-keys-batch', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/list-keys -- List all keys (standard + custom) on a record.
+             */
+            listKeys: async (data) => {
+                const response = await this.client.post('/api/v1/memory/list-keys', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/delete-keys -- Delete specific key aliases from a record.
+             * Blocks deletion if it would leave zero aliases.
+             */
+            deleteKeys: async (data) => {
+                const response = await this.client.post('/api/v1/memory/delete-keys', data);
+                return response.data;
+            },
         };
         // ============ SmartRecall Unified ============
         this.smartRecallUnified = async (data) => {
@@ -494,6 +597,31 @@ class Personize {
                 const response = await this.client.post('/api/v1/external-rag/test', {});
                 return response.data;
             },
+            /** Our LanceDB RAG: ingest documents into a project */
+            ingest: async (data) => {
+                const response = await this.client.post('/api/v1/rag/ingest', data);
+                return response.data;
+            },
+            /** Our LanceDB RAG: search a project */
+            searchProject: async (data) => {
+                const response = await this.client.post('/api/v1/rag/search', data);
+                return response.data;
+            },
+            /** Our LanceDB RAG: list projects for this org */
+            listProjects: async () => {
+                const response = await this.client.get('/api/v1/rag/projects');
+                return response.data;
+            },
+            /** Our LanceDB RAG: delete documents from a project */
+            deleteDocuments: async (data) => {
+                const response = await this.client.post('/api/v1/rag/delete', data);
+                return response.data;
+            },
+            /** Our LanceDB RAG: delete an entire project */
+            deleteProject: async (projectId) => {
+                const response = await this.client.post('/api/v1/rag/delete-project', { projectId });
+                return response.data;
+            },
         };
         // ============ Multimodal ============
         this.multimodal = {
@@ -802,6 +930,8 @@ class Personize {
             }),
             customKeyName: data.customKeyName,
             customKeyValue: data.customKeyValue,
+            name: data.name,
+            parentIdentifier: data.parentIdentifier,
             filters: data.filters,
             collectionNames: data.collectionNames || (data.collectionName ? [data.collectionName] : undefined),
         };
@@ -972,6 +1102,7 @@ class Personize {
                 type: record.type,
                 tags: record.tags,
                 enhanced: record.enhanced ?? data.enhanced,
+                extractionPrompt: data.extractionPrompt,
                 timestamp: record.timestamp,
                 speaker: record.speaker,
                 collectionNames: record.collectionName ? [record.collectionName] : undefined,
@@ -1056,6 +1187,7 @@ class Personize {
         const batchPromise = this.client.post('/api/v1/batch-memorize', {
             source: data.source || 'SDK records shorthand',
             tier: data.tier,
+            extractionPrompt: data.extractionPrompt,
             dryRun: data.dryRun,
             chunkSize: data.chunkSize,
             mapping: {

package/dist/types.d.ts

@@ -112,6 +112,103 @@ export interface GuidelineUpdatePayload {
 }
 /** @deprecated Use GuidelineUpdatePayload instead. */
 export type VariableUpdatePayload = GuidelineUpdatePayload;
+export type GovernanceAttachmentType = 'script' | 'template' | 'reference' | 'config' | 'data' | 'schema' | 'prompt' | 'image';
+export interface AttachmentAuditFinding {
+    severity: 'info' | 'warning' | 'error';
+    message: string;
+    line?: number;
+}
+export interface AttachmentAudit {
+    status: 'pending' | 'clean' | 'warnings' | 'errors';
+    findings: AttachmentAuditFinding[];
+    auditedAt: string;
+    model: string;
+}
+export interface GovernanceAttachment {
+    id: string;
+    name: string;
+    type: GovernanceAttachmentType;
+    description: string;
+    usage: string;
+    language?: string;
+    mimeType: string;
+    sizeBytes: number;
+    sha256: string;
+    preview?: string;
+    sectionHeader?: string;
+    uploadedBy: string;
+    fetchCount: number;
+    lastFetchedAt?: string;
+    audit?: AttachmentAudit;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface AttachmentUploadOptions {
+    file: Buffer | ReadableStream;
+    name?: string;
+    type: GovernanceAttachmentType;
+    description: string;
+    usage: string;
+    language?: string;
+    sectionHeader?: string;
+}
+export interface AttachmentUpdateOptions {
+    description?: string;
+    usage?: string;
+    type?: GovernanceAttachmentType;
+    language?: string;
+    sectionHeader?: string;
+}
+export interface BatchAttachmentUploadOptions {
+    files: Array<{
+        file: Buffer | ReadableStream;
+        metadata: AttachmentUploadOptions;
+    }>;
+}
+export interface SmartUpdateOptions {
+    /** Whether to operate on guidelines or collections */
+    type: 'guideline' | 'collection';
+    /** What to do with the material */
+    instruction: string;
+    /** Raw content: text, notes, JSON, meeting notes, etc. (max 50K chars) */
+    material: string;
+    /** Specific guideline/collection IDs to target. Falls back to semantic discovery. */
+    targetIds?: string[];
+    target_ids?: string[];
+    /** Execution strategy */
+    strategy?: 'suggest' | 'safe' | 'force';
+}
+export interface SmartUpdateItem {
+    itemId: string;
+    action: 'create' | 'update_section' | 'append_section' | 'add_property' | 'update_property';
+    target: string;
+    targetId?: string;
+    sectionHeader?: string;
+    reasoning: string;
+    detail: string;
+    preview: {
+        before?: string;
+        after: string;
+    };
+    hasConflict: boolean;
+    conflictDescription?: string;
+    applied: boolean;
+    createMetadata?: {
+        name?: string;
+        description?: string;
+        tags?: string[];
+        collectionName?: string;
+        entityType?: string;
+        definition?: string;
+    };
+}
+export interface SmartUpdateResponse {
+    status: 'planned' | 'applied' | 'partial';
+    creditsUsed: number;
+    items: SmartUpdateItem[];
+    summary: string;
+    warnings?: string[];
+}
 export interface GuidelineCreatePayload {
     name: string;
     value?: string;
@@ -179,10 +276,84 @@ export interface CollectionsResponse extends Array<CollectionListItem> {
     /** Cursor for the next page. Undefined when on the last page. */
     nextToken?: string;
 }
+/**
+ * Property definition for a collection.
+ *
+ * Each property defines a field that the AI extraction pipeline will populate
+ * when content is memorized against this collection.
+ *
+ * @example Single replaceable property
+ * ```ts
+ * { propertyName: 'Job Title', type: 'text', description: 'Current role', update: true }
+ * ```
+ *
+ * @example Append-only array property
+ * ```ts
+ * { propertyName: 'Meeting Notes', type: 'array', description: 'Chronological meeting log', update: false, tags: ['interaction'] }
+ * ```
+ *
+ * @example Options property with predefined values
+ * ```ts
+ * { propertyName: 'Lifecycle Stage', type: 'options', options: 'Lead, MQL, SQL, Customer', update: true }
+ * ```
+ */
+export interface CollectionPropertyDefinition {
+    /** Display name (e.g., 'Job Title', 'Deal Value'). Required for create. */
+    propertyName: string;
+    /** Internal unique ID. Auto-generated if omitted. Immutable after creation. */
+    propertyId?: string;
+    /**
+     * Machine name for filtering (e.g., 'job_title'). Auto-generated from propertyName if omitted.
+     * Immutable after creation -- used to identify which property to update in PATCH calls.
+     */
+    systemName?: string;
+    /**
+     * Data type. Aliases accepted: `'string'` -> `'text'`, `'bool'` -> `'boolean'`,
+     * `'int'`/`'float'` -> `'number'`, `'list'` -> `'array'`.
+     * @default 'text'
+     */
+    type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
+    /**
+     * Example values or comma-separated options. Most useful for `type: 'options'`.
+     * @example 'Lead, MQL, SQL, Customer, Churned'
+     */
+    options?: string | string[];
+    /**
+     * Extraction instructions for AI -- describe what this property captures and
+     * give examples of expected values. Better descriptions produce better extraction.
+     */
+    description?: string;
+    /** If true, AI automatically populates this field during extraction. */
+    autoSystem?: boolean;
+    /**
+     * `true` (default) = replaceable via 'set' operation.
+     * `false` = append-only, can only 'push' new items.
+     * Use `false` for properties that accumulate history (e.g., meeting notes, interaction log).
+     * @default true
+     */
+    update?: boolean;
+    /** Compatibility alias. `'append'` maps to `update: false`, `'replace'` to `update: true`. */
+    updateSemantics?: 'replace' | 'append';
+    /**
+     * Tags for property selection boosting during extraction.
+     * @example ['identity', 'qualification', 'vip']
+     */
+    tags?: string[];
+    /**
+     * Property status. Set to `'Deleted'` to soft-remove a property from
+     * extraction without deleting stored values.
+     * @default 'Active'
+     */
+    status?: 'Active' | 'Deleted';
+}
 export interface CollectionCreatePayload {
+    /** Display name (e.g., 'Contact Properties', 'Deal Tracker'). */
     collectionName?: string;
+    /** Optional custom ID. Auto-generated (UUID) if omitted. */
     collectionId?: string;
+    /** Description or extraction instructions for the whole collection. Helps AI understand the collection's purpose. */
     definition?: string;
+    /** Entity type: 'Contact', 'Company', 'Deal', 'Employee', or any custom type. */
     entityType?: string;
     /** Compatibility alias for collectionName. */
     name?: string;
@@ -196,40 +367,63 @@ export interface CollectionCreatePayload {
     color?: string;
     /** Accepted for compatibility; may be used to infer entityType client-side. */
     primaryKeyField?: string;
-    properties?: Array<{
-        propertyName: string;
-        propertyId?: string;
-        systemName?: string;
-        type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
-        options?: string | string[];
-        description?: string;
-        autoSystem?: boolean;
-        update?: boolean;
-        /** Compatibility alias. `append` maps to `update: false`, `replace` to `update: true`. */
-        updateSemantics?: 'replace' | 'append';
-        tags?: string[];
-        status?: 'Active' | 'Deleted';
-    }>;
+    /**
+     * Initial property definitions. Can be added later via `collections.update()`.
+     * See {@link CollectionPropertyDefinition} for the full field reference.
+     */
+    properties?: CollectionPropertyDefinition[];
     status?: 'Active' | 'Deleted';
 }
+/**
+ * Payload for `collections.update()`. **Incremental**: send only the properties
+ * you want to add or change -- existing properties not included are preserved.
+ *
+ * @example Add a single property to an existing collection
+ * ```ts
+ * await client.collections.update(collectionId, {
+ *     properties: [
+ *         { propertyName: 'Location', type: 'text', description: 'City or region', update: true },
+ *     ],
+ *     historyNote: 'Added Location property',
+ * });
+ * ```
+ *
+ * @example Add multiple properties at once
+ * ```ts
+ * await client.collections.update(collectionId, {
+ *     properties: [
+ *         { propertyName: 'Budget Range', type: 'options', options: '<50K, 50K-200K, 200K-1M, >1M', update: true },
+ *         { propertyName: 'Decision Timeline', type: 'text', description: 'When they plan to buy', update: true },
+ *         { propertyName: 'Objections Log', type: 'array', description: 'Sales objections', update: false },
+ *     ],
+ *     historyNote: 'Added qualification properties for lead scoring',
+ * });
+ * ```
+ *
+ * @example Soft-delete a property
+ * ```ts
+ * await client.collections.update(collectionId, {
+ *     properties: [
+ *         { propertyName: 'Old Field', systemName: 'old_field', status: 'Deleted' },
+ *     ],
+ *     historyNote: 'Retired Old Field property',
+ * });
+ * ```
+ */
 export interface CollectionUpdatePayload {
+    /** Updated display name (only if renaming). */
     collectionName?: string;
+    /** Updated description or extraction instructions. */
     definition?: string;
     entityType?: string;
-    properties?: Array<{
-        propertyId?: string;
-        propertyName?: string;
-        systemName?: string;
-        type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
-        options?: string | string[];
-        description?: string;
-        autoSystem?: boolean;
-        update?: boolean;
-        /** Compatibility alias. `append` maps to `update: false`, `replace` to `update: true`. */
-        updateSemantics?: 'replace' | 'append';
-        tags?: string[];
-        status?: 'Active' | 'Deleted';
-    }>;
+    /**
+     * Properties to add or modify. **Incremental** -- send only new or changed
+     * properties. Existing properties not listed here are preserved unchanged.
+     * See {@link CollectionPropertyDefinition} for the full field reference.
+     */
+    properties?: CollectionPropertyDefinition[];
+    /** Human-readable change note for the audit trail. */
+    historyNote?: string;
     status?: 'Active' | 'Deleted';
 }
 export interface CollectionHistoryOptions {
@@ -650,6 +844,8 @@ export interface MemorizeOptions {
     customKeyName?: string;
     /** Custom key value — the unique identifier value (e.g. 'S12345', 'https://linkedin.com/in/johndoe'). */
     customKeyValue?: string;
+    /** Optional extraction focus instructions for the LLM (max 500 chars). Guides what the extraction prioritizes. Example: "Focus on pricing tiers and competitive positioning." */
+    extractionPrompt?: string;
     /** Enable enhanced dual extraction (structured + free-form). */
     enhanced?: boolean;
     /** Compatibility shorthand for structured property writes. */
@@ -678,6 +874,10 @@ export interface MemorizeOptions {
     deviceId?: string;
     /** Content ID for entity scoping. */
     contentId?: string;
+    /** IDv2: Human name for weak identity resolution */
+    name?: string;
+    /** IDv2: Parent entity's natural key for disambiguation (e.g., company domain) */
+    parentIdentifier?: string;
 }
 /** @deprecated Use MemorizeOptions instead. */
 export type MemorizeProOptions = MemorizeOptions;
@@ -724,6 +924,10 @@ export interface SmartRecallOptions {
     customKeyName?: string;
     /** Custom key value — the unique identifier value. */
     customKeyValue?: string;
+    /** IDv2: Human name for weak identity resolution */
+    name?: string;
+    /** IDv2: Parent entity's natural key for disambiguation (e.g., company domain) */
+    parentIdentifier?: string;
     /** Scope results to specific collections by ID. */
     collectionIds?: string[];
     /** Scope results to specific collections by name (resolved server-side, case-insensitive). */
@@ -798,6 +1002,10 @@ export interface RecallOptions {
     deviceId?: string;
     /** Content ID for entity scoping. */
     contentId?: string;
+    /** IDv2: Human name for weak identity resolution */
+    name?: string;
+    /** IDv2: Parent entity's natural key for disambiguation (e.g., company domain) */
+    parentIdentifier?: string;
     /** Additional filters. */
     filters?: Record<string, unknown>;
     /** Scope results to specific collections by ID. */
@@ -826,6 +1034,16 @@ export interface RecallResultItem {
     name?: string;
     properties?: Record<string, PropertyValue>;
     metadata?: Record<string, unknown>;
+    /** IDv2: Identity resolution state */
+    resolutionState?: 'resolved' | 'provisional' | 'merged';
+    /** IDv2: How the record was resolved */
+    resolutionSource?: string;
+    /** IDv2: Known aliases for this record */
+    knownAliases?: Array<{
+        kind: string;
+        value: string;
+        strength: 'strong' | 'weak';
+    }>;
     [key: string]: unknown;
 }
 export interface RecallResponse extends Array<RecallResultItem> {
@@ -880,6 +1098,8 @@ export interface BatchMemorizeOptions {
     chunkSize?: number;
     /** Compatibility flag accepted and ignored when not needed. */
     enhanced?: boolean;
+    /** Optional extraction focus instructions applied to all items in the batch (max 500 chars). */
+    extractionPrompt?: string;
     /** Compatibility shorthand accepted by the SDK and normalized client-side. */
     records?: BatchMemorizeRecord[];
 }
@@ -1316,6 +1536,104 @@ export interface CancelDeletionResult {
     };
     warning?: string;
 }
+/** Lookup fields -- provide any ONE to identify the target record. */
+export interface KeyLookupFields {
+    recordId?: string;
+    email?: string;
+    websiteUrl?: string;
+    phoneNumber?: string;
+    postalCode?: string;
+    deviceId?: string;
+    contentId?: string;
+    customKeyName?: string;
+    customKeyValue?: string;
+}
+export interface UpdateKeysOptions extends KeyLookupFields {
+    /** Entity type (e.g. 'contact', 'company'). */
+    type: string;
+    /** Keys to register. Both standard CRM keys and custom keys accepted. */
+    keys: Record<string, string>;
+}
+export interface UpdateKeysResponse {
+    /** Resolved record ID (useful when looked up by CRM key). */
+    recordId: string;
+    /** Set if the original record was merged into this one. */
+    redirectedFrom?: string;
+    /** Number of keys successfully registered. */
+    registered: number;
+    /** Keys that conflicted with existing aliases on different records. */
+    conflicts: Array<{
+        keyName: string;
+        keyValue: string;
+        existingRecordId: string;
+    }>;
+    /** Keys that were rejected (e.g. empty values, weak alias kinds). */
+    rejected?: Array<{
+        keyName: string;
+        reason: string;
+    }>;
+}
+export interface UpdateKeysBatchOptions {
+    /** Array of records to register keys for. Max 100. */
+    records: Array<KeyLookupFields & {
+        /** Entity type. */
+        type: string;
+        /** Keys to register. Max 50 per record. */
+        keys: Record<string, string>;
+    }>;
+}
+export interface UpdateKeysBatchResponse {
+    /** Per-record registration results. */
+    results: Array<{
+        recordId: string;
+        registered: number;
+        conflicts: Array<{
+            keyName: string;
+            keyValue: string;
+            existingRecordId: string;
+        }>;
+    }>;
+    /** Records that were not found (echoes back lookup fields). */
+    notFound: Array<Record<string, string>>;
+}
+export interface ListKeysOptions extends KeyLookupFields {
+    /** Entity type. */
+    type: string;
+}
+export interface KeyEntry {
+    kind: string;
+    value: string;
+    standard: boolean;
+    createdAt: string;
+    lastSeenAt: string;
+}
+export interface ListKeysResponse {
+    recordId: string;
+    redirectedFrom?: string;
+    keys: KeyEntry[];
+}
+export interface DeleteKeysOptions extends KeyLookupFields {
+    /** Entity type. */
+    type: string;
+    /** Keys to delete. */
+    keys: Array<{
+        keyName: string;
+        keyValue: string;
+    }>;
+}
+export interface DeleteKeysResponse {
+    recordId: string;
+    /** Number of keys deleted. */
+    deleted: number;
+    /** Number of keys not found. */
+    notFound: number;
+    /** Keys blocked from deletion (e.g. last remaining alias). */
+    blocked?: Array<{
+        keyName: string;
+        keyValue: string;
+        reason: string;
+    }>;
+}
 /** Comparison operators for deterministic property filters. */
 export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' | 'isEmpty';
 export interface PropertyFilterCondition {
@@ -1760,7 +2078,7 @@ export interface SegmentResponse {
 }
 /** SmartRecall Unified: 1 endpoint replaces 10 for LLMs/agents. Natural language in, structured intelligence out. */
 export interface SmartRecallUnifiedOptions {
-    /** Natural language query describing what you need from memory. Be specific. */
+    /** Natural language query describing what you need from memory. Be specific about what, who, how many. */
     message: string;
     /** Scope to specific records by identifier. Omit for org-wide queries. */
     identifiers?: {
@@ -1768,6 +2086,16 @@ export interface SmartRecallUnifiedOptions {
         websites?: string[];
         recordIds?: string[];
         type?: string;
+        phoneNumbers?: string[];
+        postalCodes?: string[];
+        deviceIds?: string[];
+        contentIds?: string[];
+        customKeyName?: string;
+        customKeyValue?: string;
+        /** IDv2: person or entity name for identity resolution without email. */
+        name?: string;
+        /** IDv2: parent domain or company (e.g., "acme.com") for name disambiguation. */
+        parentIdentifier?: string;
     };
     /** Control response depth. Auto-detected from query if omitted. */
     responseDetail?: 'ids' | 'labels' | 'summary' | 'context' | 'full';
@@ -1775,6 +2103,8 @@ export interface SmartRecallUnifiedOptions {
     tokenBudget?: number;
     /** Classification mode. "fast" (~50ms rules), "deep" (~500ms LLM), "auto" (default). */
     mode?: 'fast' | 'deep' | 'auto';
+    /** Session ID for follow-up queries. Same sessionId links queries so pronouns resolve to previous results. */
+    sessionId?: string;
     /** Include results from external RAG source (if configured). Default: true. */
     includeExternalRag?: boolean;
     /** Include multimodal search results (if enabled). Default: false. */
@@ -1785,6 +2115,7 @@ export interface SmartRecallUnifiedRecord {
     type?: string;
     email?: string;
     websiteUrl?: string;
+    displayName?: string;
     label?: string;
     summary?: Record<string, unknown>;
     context?: string;
@@ -1795,9 +2126,37 @@ export interface SmartRecallUnifiedRecord {
         source?: string;
     }[];
     properties?: Record<string, unknown>;
+    highlightedProperties?: Record<string, {
+        value: unknown;
+        relevant: boolean;
+        confidence?: number;
+    }>;
     score?: number;
     relevanceTier?: 'direct' | 'partial' | 'might';
     sources?: string[];
+    resolutionState?: 'resolved' | 'provisional' | 'merged';
+    freshness?: {
+        score: number;
+        memoryCount?: number;
+    };
+    completeness?: {
+        score: number;
+        filledProperties: string[];
+        missingProperties: string[];
+        memoryCount: number;
+        propertyCount: number;
+    };
+}
+export interface SmartRecallUnifiedWarning {
+    type: 'potential_duplicate' | 'stale_record' | 'missing_identity' | 'missing_relationship';
+    records: string[];
+    reason: string;
+    suggestedAction?: string;
+}
+export interface SmartRecallUnifiedSuggestedAction {
+    action: 'enrich_identity' | 'memorize_update' | 'merge_records' | 'create_relationship' | 'external_rag_lookup';
+    records?: string[];
+    reason: string;
 }
 export interface SmartRecallUnifiedResponse {
     success: boolean;
@@ -1809,6 +2168,8 @@ export interface SmartRecallUnifiedResponse {
         confidence: number;
     };
     records: SmartRecallUnifiedRecord[];
+    warnings?: SmartRecallUnifiedWarning[];
+    suggestedActions?: SmartRecallUnifiedSuggestedAction[];
     meta: {
         totalMatched: number;
         returned: number;
@@ -1817,6 +2178,13 @@ export interface SmartRecallUnifiedResponse {
         creditsCharged: number;
         latencyMs: number;
         sources: string[];
+        sessionId?: string;
+        identityResolution?: {
+            resolverUsed: boolean;
+            provisionalCount: number;
+            mergedCount: number;
+            resolvedCount: number;
+        };
     };
 }
 export interface ExternalRAGConfigOptions {
@@ -1859,3 +2227,33 @@ export interface MultimodalSearchResult {
     sourceUrl?: string;
     mimeType?: string;
 }
+export interface RAGIngestOptions {
+    projectId: string;
+    documents: {
+        id?: string;
+        text: string;
+        source?: string;
+        sourceUrl?: string;
+        title?: string;
+        metadata?: Record<string, unknown>;
+    }[];
+}
+export interface RAGSearchOptions {
+    projectId: string;
+    query: string;
+    limit?: number;
+    minScore?: number;
+}
+export interface RAGSearchResult {
+    id: string;
+    text: string;
+    score: number;
+    source: string;
+    sourceUrl?: string;
+    title?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface RAGDeleteOptions {
+    projectId: string;
+    documentIds: string[];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@personize/sdk",
-    "version": "0.7.3",
+    "version": "0.7.4",
     "description": "Official Personize SDK",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",
@@ -44,4 +44,4 @@
     "dependencies": {
         "axios": "^1.6.0"
     }
-}
+}