@personize/sdk 0.6.4 → 0.6.5

package/README.md

@@ -38,6 +38,7 @@ console.log(me.data.plan.limits);
 | **AI** | | |
 | POST | `/api/v1/ai/smart-guidelines` | `client.ai.smartGuidelines(opts)` |
 | POST | `/api/v1/prompt` | `client.ai.prompt(opts)` |
+| POST | `/api/v1/prompt` (stream) | `client.ai.promptStream(opts)` |
 | **Memory** | | |
 | POST | `/api/v1/memorize` | `client.memory.memorize(opts)` |
 | POST | `/api/v1/smart-recall` | `client.memory.smartRecall(opts)` |
@@ -45,6 +46,7 @@ console.log(me.data.plan.limits);
 | POST | `/api/v1/search` | `client.memory.search(opts)` |
 | POST | `/api/v1/batch-memorize` | `client.memory.memorizeBatch(opts)` |
 | POST | `/api/v1/smart-memory-digest` | `client.memory.smartDigest(opts)` |
+| POST | `/api/v1/memory/properties` | `client.memory.properties(opts)` |
 | **Guidelines** | | |
 | GET | `/api/v1/guidelines` | `client.guidelines.list()` |
 | POST | `/api/v1/guidelines` | `client.guidelines.create(payload)` |
@@ -185,6 +187,97 @@ console.log(research.data?.outputs?.company_profile);
 console.log(research.data?.evaluation?.finalScore);
 ```
 
+### Streaming Prompt Execution
+
+`promptStream()` returns an async generator that yields Server-Sent Events as they arrive. Use this for real-time UI updates, progressive output delivery, or when you need structured outputs as soon as each one finishes generating.
+
+```typescript
+import type { PromptSSEEvent } from '@personize/sdk';
+
+// Stream with structured outputs — events arrive as each output closes
+for await (const event of client.ai.promptStream({
+    prompt: 'Generate a hero section and social proof for our landing page',
+    outputs: [
+        { name: 'hero' },
+        { name: 'social_proof' },
+    ],
+})) {
+    switch (event.type) {
+        case 'text':
+            // Raw LLM text chunks (everything outside <output> markers)
+            process.stdout.write(event.chunk);
+            break;
+
+        case 'output':
+            // A named output extracted — fired once per output as soon as </output> closes
+            // event.data is already parsed (JSON object or plain string)
+            console.log(`Output "${event.name}":`, event.data);
+            break;
+
+        case 'done':
+            // Final event — includes all outputs, evaluation, and metadata
+            console.log('All outputs:', event.outputs);
+            console.log('Metadata:', event.metadata);
+            break;
+
+        case 'error':
+            // Non-fatal error during streaming
+            console.error('Stream error:', event.message);
+            break;
+    }
+}
+```
+
+**SSE Event Types:**
+
+| Event | Frequency | Description |
+| :--- | :--- | :--- |
+| `text` | Many per response | Plain text chunks from the LLM |
+| `output` | Once per named output | Extracted output (JSON or string) — fired as soon as `</output>` closes |
+| `step_complete` | Once per instruction step | Multi-step mode: step metadata |
+| `done` | Once at end | Final reconciliation with all outputs + metadata |
+| `error` | 0 or more | Non-fatal streaming errors |
+
+**Options:**
+
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `streamTimeout` | number | `120000` | Overall stream timeout in ms |
+| `signal` | AbortSignal | — | External abort signal for cancellation |
+
+All other `PromptOptions` parameters (`outputs`, `context`, `instructions`, `tier`, `memorize`, `evaluate`, etc.) are supported.
+
+**Cancellation:**
+
+```typescript
+const controller = new AbortController();
+setTimeout(() => controller.abort(), 5000); // cancel after 5s
+
+for await (const event of client.ai.promptStream({
+    prompt: '...',
+    signal: controller.signal,
+})) {
+    // ...
+}
+```
+
+#### Entity Identifiers
+
+All memory endpoints support multiple CRM key types for entity scoping:
+
+| Key | Use case |
+|-----|----------|
+| `email` | Contact lookup |
+| `websiteUrl` | Company lookup |
+| `recordId` | Direct record ID |
+| `customKeyName` + `customKeyValue` | Custom CRM field (e.g. `hubspot_id`) |
+| `phoneNumber` | Phone-based lookup |
+| `postalCode` | Location-based lookup |
+| `deviceId` | Device-based lookup |
+| `contentId` | Content-based lookup |
+
+You can pass multiple keys simultaneously for better matching.
+
 ### Memory (RAG)
 
 ```typescript
@@ -199,21 +292,20 @@ const memorized = await client.memory.memorize({
 });
 console.log(memorized.data?.recordId); // REC#<hex> — deterministic, use for recall/digest
 
-// Smart recall — advanced recall with reflection
+// Smart recall — deep mode (default): reflection + answer generation, ~10-20s, 2 credits
 const results = await client.memory.smartRecall({
     query: 'What does John prefer?',
     limit: 5,
     minScore: 0.7,
-    enable_reflection: true,
-    generate_answer: true,
+    mode: 'deep',
 });
 
-// Fast recall — low-latency mode (~500ms), guaranteed min 10 results
+// Smart recall — fast mode: skips reflection, ~500ms, 1 credit
 const fast = await client.memory.smartRecall({
     query: 'contact info for John',
     email: 'john@example.com',
-    fast_mode: true,
-    // min_results: 10 (default in fast_mode — always returns top N even below score threshold)
+    mode: 'fast',
+    // min_results: 10 (default in fast mode — always returns top N even below score threshold)
 });
 
 // Custom keys — bring your own identifier for any entity type
@@ -239,7 +331,7 @@ const student = await client.memory.smartRecall({
     type: 'Student',
     customKeyName: 'studentNumber',
     customKeyValue: 'S-2024-1234',
-    fast_mode: true,
+    mode: 'fast',
 });
 
 // Direct recall — DynamoDB lookup: properties + freeform memories (no AI, type required)
@@ -377,6 +469,38 @@ console.log(digest.data?.compiledContext); // ready-to-use markdown for LLM prom
 
 ```
 
+### Get Record Properties
+
+Fetch current property values for a record, joined with collection schema descriptions and the `update` flag.
+
+```typescript
+// Get specific properties with schema info
+const result = await client.memory.properties({
+  email: 'john@acme.com',
+  propertyNames: ['Tasks', 'Lifecycle Stage'],
+  nonEmpty: true,
+});
+
+for (const prop of result.data.properties) {
+  console.log(`${prop.name}: ${JSON.stringify(prop.value)}`);
+  console.log(`  Type: ${prop.type}, Update: ${prop.update}`);
+  console.log(`  Description: ${prop.description}`);
+}
+```
+
+Each property includes:
+- `value` — current value
+- `description` — from the collection schema, tells AI how to interpret/update
+- `update` — `true` means replaceable (use `memory.update()` with `propertyValue`), `false` means append-only (use `arrayPush`)
+- `type` — property type (`text`, `number`, `boolean`, `array`, `date`, `options`)
+- `collectionName` — which collection this property belongs to
+
+Options:
+- `propertyNames` — filter to specific properties (recommended to save tokens)
+- `includeDescriptions` — join with collection schema (default: `true`)
+- `nonEmpty` — exclude null/empty values (default: `false`)
+- Identifiers: `email`, `websiteUrl`, `recordId`, `customKeyName`+`customKeyValue`
+
 ### Agents
 
 ```typescript
@@ -456,12 +580,12 @@ console.log(evaluation.data.summary.propertiesOptimized);
 
 | Operation | Mode | Credits/Call |
 | :--- | :--- | :--- |
-| Smart Recall | `fast_mode: true` | 1 |
-| Smart Recall | `fast_mode: false` (deep) | 1 |
+| Smart Recall | `mode: 'fast'` | 1 |
+| Smart Recall | `mode: 'deep'` | 2 |
 | Smart Guidelines | `mode: 'fast'` | 1 |
 | Smart Guidelines | `mode: 'deep'` | 1 |
 
-All read operations (recall, smart recall, smart guidelines, smart context) charge a flat **1 credit per call** regardless of mode. Mode choice affects latency and depth, not cost.
+Smart Recall cost depends on mode: fast = 1 credit, deep = 2 credits. All other read operations (recall, smart guidelines, smart context) charge a flat **1 credit per call**.
 
 1 credit = $0.01.
 
@@ -496,6 +620,33 @@ await client.ai.prompt({
 
 Response metadata includes `byok: true` and `creditsCharged` reflecting the flat 5-credit charge.
 
+## Smart Recall Modes
+
+The `mode` parameter controls smart recall behavior:
+
+| Mode | Latency | Credits | Description |
+| :--- | :--- | :--- | :--- |
+| `"fast"` | ~500ms | 1 | Skips reflection and answer generation. Returns raw vector results with guaranteed minimum count. |
+| `"deep"` | ~10-20s | 2 | Enables reflection + answer generation for higher-quality, synthesized responses. |
+
+Default is `"deep"`. The `mode` parameter takes precedence over the individual `enable_reflection`, `generate_answer`, and `fast_mode` flags. If `mode` is set, those flags are ignored.
+
+#### Recency Bias
+
+Use `prefer_recent` to boost recent memories with exponential decay:
+
+```typescript
+const result = await client.memory.smartRecall({
+  query: "what changed on this contact recently?",
+  email: "john@acme.com",
+  mode: "deep",
+  prefer_recent: true,
+  recency_half_life_days: 30, // aggressive: 30-day half-life
+});
+```
+
+Default half-life is 90 days. A memory 90 days old scores ~37% of its original relevance. Set to 7-30 for "what happened this week/month" queries.
+
 ## Best Practices: Query Crafting for smartRecall
 
 The `smartRecall` endpoint uses vector similarity search. Query quality directly impacts result relevance. When building AI pipelines that call `smartRecall`, the **AI agent is responsible for crafting embedding-friendly queries**.
@@ -518,11 +669,11 @@ const bad = await client.memory.smartRecall({ query: 'Tell me about this contact
 const good = await client.memory.smartRecall({
     query: `${contactName} role company background interests preferences`,
     email,
-    fast_mode: true,
+    mode: 'fast',
 });
 ```
 
-**Guaranteed minimum results:** In `fast_mode`, `smartRecall` guarantees at least 10 results (configurable via `min_results`) even when scores fall below the threshold. This ensures your AI workflow always has context to reason about — it can then decide whether the data is sufficient or not.
+**Guaranteed minimum results:** In `mode: 'fast'`, `smartRecall` guarantees at least 10 results (configurable via `min_results`) even when scores fall below the threshold. This ensures your AI workflow always has context to reason about — it can then decide whether the data is sufficient or not.
 
 ## Configuration
 
@@ -543,23 +694,23 @@ const client = new Personize({
 });
 ```
 
-## Migration from 0.6.2
-
-**New in 0.6.3:**
-
-| Feature | Details |
-| :--- | :--- |
-| `evaluationCriteria` on `PromptOptions` | Compatibility alias for `evaluate: { criteria, serverSide: true }` |
-| `message` on `RecallOptions` / `SmartRecallOptions` | Compatibility alias for `query` |
-| Legacy `memory.recall()` routing | If you call `recall()` with legacy advanced-recall-style inputs (`message`, `limit`, omitted `type`, collection-name scoping), the SDK routes to `/smart-recall` automatically |
-| Shorthand semantic `memory.search()` | `search({ query, limit, collectionName })` is accepted and routed to `/smart-recall` when no filter groups are provided |
-| `collectionName` / `collectionNames` on `memorize()` | Collection names are resolved client-side into `collectionIds` |
-| Legacy collection payload aliases | `collections.create()` now accepts `name`, `slug`, `description`, array `options`, and `updateSemantics` |
-| `records` shorthand on `memorizeBatch()` | Accepts record-style input and normalizes it client-side into `memorize()` + `/batch-memorize` calls |
-
-See [SDK_0_6_3_COMPATIBILITY_CHANGES.md](SDK_0_6_3_COMPATIBILITY_CHANGES.md) for the full design notes and tradeoffs.
-
-## Migration from 0.5.x
+## Migration from 0.6.2
+
+**New in 0.6.3:**
+
+| Feature | Details |
+| :--- | :--- |
+| `evaluationCriteria` on `PromptOptions` | Compatibility alias for `evaluate: { criteria, serverSide: true }` |
+| `message` on `RecallOptions` / `SmartRecallOptions` | Compatibility alias for `query` |
+| Legacy `memory.recall()` routing | If you call `recall()` with legacy advanced-recall-style inputs (`message`, `limit`, omitted `type`, collection-name scoping), the SDK routes to `/smart-recall` automatically |
+| Shorthand semantic `memory.search()` | `search({ query, limit, collectionName })` is accepted and routed to `/smart-recall` when no filter groups are provided |
+| `collectionName` / `collectionNames` on `memorize()` | Collection names are resolved client-side into `collectionIds` |
+| Legacy collection payload aliases | `collections.create()` now accepts `name`, `slug`, `description`, array `options`, and `updateSemantics` |
+| `records` shorthand on `memorizeBatch()` | Accepts record-style input and normalizes it client-side into `memorize()` + `/batch-memorize` calls |
+
+See [SDK_0_6_3_COMPATIBILITY_CHANGES.md](SDK_0_6_3_COMPATIBILITY_CHANGES.md) for the full design notes and tradeoffs.
+
+## Migration from 0.5.x
 
 **New in 0.6.0:**
 

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, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, RecallResponse, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } 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 } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -105,6 +105,28 @@ export declare class Personize {
          * Use `memorize` to auto-save outputs and tool results to memory.
          */
         prompt: (options: PromptOptions) => Promise<ApiResponse<PromptResponse>>;
+        /**
+         * POST /api/v1/prompt (stream: true) — Stream prompt execution as Server-Sent Events.
+         *
+         * Returns an async generator that yields SSE events as they arrive:
+         * - `text`: plain text chunks from the LLM
+         * - `output`: a named output extracted when its </output> marker closes
+         * - `step_complete`: fired after each instruction step (multi-step mode)
+         * - `done`: final event with all outputs, evaluation, and metadata
+         * - `error`: non-fatal error during streaming
+         *
+         * @example
+         * ```ts
+         * for await (const event of personize.ai.promptStream({
+         *   prompt: 'Write a hero section',
+         *   outputs: [{ name: 'headline' }, { name: 'subtitle' }],
+         * })) {
+         *   if (event.type === 'output') console.log(event.name, event.data);
+         *   if (event.type === 'done') console.log('Finished:', event.metadata);
+         * }
+         * ```
+         */
+        promptStream: (options: PromptStreamOptions) => AsyncGenerator<PromptSSEEvent>;
     };
     agents: {
         /**
@@ -152,6 +174,61 @@ export declare class Personize {
          * Combines DynamoDB properties + LanceDB memories into a token-budgeted markdown block.
          */
         smartDigest: (data: SmartDigestOptions) => Promise<ApiResponse<SmartDigestResponse>>;
+        /**
+         * POST /api/v1/memory/update — Update a single property or freeform memory.
+         *
+         * For property updates: pass `propertyName` + `propertyValue` (or array operations).
+         * For freeform edits: pass `memoryId` + `text`.
+         * Use `expectedVersion` for optimistic concurrency (409 on mismatch).
+         */
+        update: (data: UpdatePropertyOptions) => Promise<ApiResponse<UpdateResult>>;
+        /**
+         * POST /api/v1/memory/bulk-update — Update multiple properties on a record in one request.
+         * Use `expectedVersion` for optimistic concurrency (checked before any writes).
+         */
+        bulkUpdate: (data: BulkUpdateOptions) => Promise<ApiResponse<BulkUpdateResult>>;
+        /**
+         * POST /api/v1/memory/delete — Soft-delete memories (30-day recovery window).
+         * Deleted items are excluded from all reads. Use `cancelDeletion` to restore.
+         */
+        delete: (data: DeleteMemoriesOptions) => Promise<ApiResponse<DeletionResult>>;
+        /**
+         * POST /api/v1/memory/delete-record — Soft-delete all memories for a record (30-day recovery).
+         */
+        deleteRecord: (data: DeleteRecordOptions) => Promise<ApiResponse<DeletionResult>>;
+        /**
+         * POST /api/v1/memory/cancel-deletion — Cancel a pending soft-delete within the 30-day window.
+         * Returns 409 DELETION_FINALIZED if the window has expired.
+         */
+        cancelDeletion: (data: CancelDeletionOptions) => Promise<ApiResponse<CancelDeletionResult>>;
+        /**
+         * POST /api/v1/memory/property-history — Query property change history for a record.
+         * Supports filtering by property name, time range, and cursor-based pagination.
+         */
+        propertyHistory: (data: PropertyHistoryOptions) => Promise<ApiResponse<PropertyHistoryResult>>;
+        /**
+         * POST /api/v1/memory/query-properties — LLM-powered search across property values.
+         * Finds records where a property value matches a natural-language query.
+         */
+        queryProperties: (data: QueryPropertiesOptions) => Promise<ApiResponse<QueryPropertiesResult>>;
+        /**
+         * POST /api/v1/memory/filter-by-property — Deterministic property filter (no LLM, no token cost).
+         * Finds records where property values match structured conditions.
+         *
+         * @example
+         * ```ts
+         * const result = await client.memory.filterByProperty({
+         *   conditions: [{ propertyName: 'deal_stage', operator: 'equals', value: 'closed_won' }],
+         *   type: 'Company',
+         *   limit: 100,
+         * });
+         * ```
+         */
+        filterByProperty: (data: FilterByPropertyOptions) => Promise<ApiResponse<FilterByPropertyResult>>;
+        /**
+         * POST /api/v1/properties — Get record properties with schema descriptions.
+         */
+        properties: (data: GetPropertiesOptions) => Promise<ApiResponse<GetPropertiesResponse>>;
     };
     evaluate: {
         /**

package/dist/client.js

@@ -169,6 +169,34 @@ class Personize {
                 const response = await this.client.post('/api/v1/prompt', normalizedOptions);
                 return response.data;
             },
+            /**
+             * POST /api/v1/prompt (stream: true) — Stream prompt execution as Server-Sent Events.
+             *
+             * Returns an async generator that yields SSE events as they arrive:
+             * - `text`: plain text chunks from the LLM
+             * - `output`: a named output extracted when its </output> marker closes
+             * - `step_complete`: fired after each instruction step (multi-step mode)
+             * - `done`: final event with all outputs, evaluation, and metadata
+             * - `error`: non-fatal error during streaming
+             *
+             * @example
+             * ```ts
+             * for await (const event of personize.ai.promptStream({
+             *   prompt: 'Write a hero section',
+             *   outputs: [{ name: 'headline' }, { name: 'subtitle' }],
+             * })) {
+             *   if (event.type === 'output') console.log(event.name, event.data);
+             *   if (event.type === 'done') console.log('Finished:', event.metadata);
+             * }
+             * ```
+             */
+            promptStream: (options) => {
+                const normalizedOptions = this.normalizePromptOptions({ ...options, stream: true });
+                const baseURL = this.client.defaults.baseURL || 'https://agent.personize.ai';
+                const authHeader = this.client.defaults.headers?.['Authorization'];
+                const streamTimeout = options.streamTimeout ?? 120000;
+                return streamPromptSSE(baseURL, authHeader, normalizedOptions, streamTimeout, options.signal);
+            },
         };
         this.agents = {
             /**
@@ -330,6 +358,98 @@ class Personize {
                 const response = await this.client.post('/api/v1/smart-memory-digest', data);
                 return response.data;
             },
+            /**
+             * POST /api/v1/memory/update — Update a single property or freeform memory.
+             *
+             * For property updates: pass `propertyName` + `propertyValue` (or array operations).
+             * For freeform edits: pass `memoryId` + `text`.
+             * Use `expectedVersion` for optimistic concurrency (409 on mismatch).
+             */
+            update: async (data) => {
+                const response = await this.client.post('/api/v1/memory/update', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/bulk-update — Update multiple properties on a record in one request.
+             * Use `expectedVersion` for optimistic concurrency (checked before any writes).
+             */
+            bulkUpdate: async (data) => {
+                const response = await this.client.post('/api/v1/memory/bulk-update', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/delete — Soft-delete memories (30-day recovery window).
+             * Deleted items are excluded from all reads. Use `cancelDeletion` to restore.
+             */
+            delete: async (data) => {
+                const response = await this.client.post('/api/v1/memory/delete', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/delete-record — Soft-delete all memories for a record (30-day recovery).
+             */
+            deleteRecord: async (data) => {
+                const response = await this.client.post('/api/v1/memory/delete-record', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/cancel-deletion — Cancel a pending soft-delete within the 30-day window.
+             * Returns 409 DELETION_FINALIZED if the window has expired.
+             */
+            cancelDeletion: async (data) => {
+                const response = await this.client.post('/api/v1/memory/cancel-deletion', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/property-history — Query property change history for a record.
+             * Supports filtering by property name, time range, and cursor-based pagination.
+             */
+            propertyHistory: async (data) => {
+                const response = await this.client.post('/api/v1/memory/property-history', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/query-properties — LLM-powered search across property values.
+             * Finds records where a property value matches a natural-language query.
+             */
+            queryProperties: async (data) => {
+                const response = await this.client.post('/api/v1/memory/query-properties', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/memory/filter-by-property — Deterministic property filter (no LLM, no token cost).
+             * Finds records where property values match structured conditions.
+             *
+             * @example
+             * ```ts
+             * const result = await client.memory.filterByProperty({
+             *   conditions: [{ propertyName: 'deal_stage', operator: 'equals', value: 'closed_won' }],
+             *   type: 'Company',
+             *   limit: 100,
+             * });
+             * ```
+             */
+            filterByProperty: async (data) => {
+                const response = await this.client.post('/api/v1/memory/filter-by-property', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/properties — Get record properties with schema descriptions.
+             */
+            properties: async (data) => {
+                const response = await this.client.post('/api/v1/properties', {
+                    email: data.email,
+                    websiteUrl: data.websiteUrl || data.website_url,
+                    recordId: data.recordId || data.record_id,
+                    type: data.type,
+                    customKeyName: data.customKeyName,
+                    customKeyValue: data.customKeyValue,
+                    propertyNames: data.propertyNames,
+                    includeDescriptions: data.includeDescriptions,
+                    nonEmpty: data.nonEmpty,
+                });
+                return response.data;
+            },
         };
         this.evaluate = {
             /**
@@ -487,7 +607,7 @@ class Personize {
     }
     normalizePromptOptions(options) {
         if (!options.evaluationCriteria || options.evaluate) {
-            const { evaluationCriteria, ...rest } = options;
+            const { evaluationCriteria: _ec, ...rest } = options;
             return rest;
         }
         const { evaluationCriteria, ...rest } = options;
@@ -550,7 +670,7 @@ class Personize {
         };
     }
     normalizeRecallOptions(data) {
-        const { message, limit, collectionName, collectionNames, ...rest } = data;
+        const { message, limit: _limit, collectionName: _collectionName, collectionNames: _collectionNames, ...rest } = data;
         return {
             ...rest,
             query: data.query || message || '',
@@ -790,3 +910,124 @@ class Personize {
     }
 }
 exports.Personize = Personize;
+// ────────────────────────────── SSE Stream Parser ──────────────────────────────
+/**
+ * Initiates a streaming prompt request and yields SSE events.
+ * Extracted as a standalone function to avoid `this` binding issues with async generators.
+ */
+async function* streamPromptSSE(baseURL, authHeader, options, streamTimeout, signal) {
+    const controller = new AbortController();
+    const timeoutId = setTimeout(() => controller.abort(), streamTimeout);
+    // Link external signal if provided
+    if (signal) {
+        if (signal.aborted) {
+            clearTimeout(timeoutId);
+            controller.abort();
+        }
+        else {
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+    }
+    let response;
+    try {
+        response = await fetch(`${baseURL}/api/v1/prompt`, {
+            method: 'POST',
+            headers: {
+                'Authorization': authHeader,
+                'Content-Type': 'application/json',
+            },
+            body: JSON.stringify(options),
+            signal: controller.signal,
+        });
+    }
+    catch (err) {
+        clearTimeout(timeoutId);
+        throw new Error(`Prompt stream connection failed: ${err instanceof Error ? err.message : err}`);
+    }
+    if (!response.ok) {
+        clearTimeout(timeoutId);
+        const errorBody = await response.text().catch(() => '');
+        throw new Error(`Prompt stream failed (${response.status}): ${errorBody}`);
+    }
+    if (!response.body) {
+        clearTimeout(timeoutId);
+        throw new Error('Prompt stream: response body is null');
+    }
+    try {
+        yield* parseSSEStream(response.body);
+    }
+    finally {
+        clearTimeout(timeoutId);
+    }
+}
+/**
+ * Parses a ReadableStream of SSE bytes into typed PromptSSEEvent objects.
+ *
+ * Handles:
+ * - Partial chunks split across reads
+ * - Multi-line `data:` fields (accumulated per event)
+ * - Empty lines as event separators
+ * - Graceful end-of-stream
+ */
+async function* parseSSEStream(body) {
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            buffer += decoder.decode(value, { stream: true });
+            // Process complete events (separated by double newline)
+            const parts = buffer.split('\n\n');
+            // Last part may be incomplete — keep it in buffer
+            buffer = parts.pop() || '';
+            for (const part of parts) {
+                const dataLines = [];
+                for (const line of part.split('\n')) {
+                    if (line.startsWith('data: ')) {
+                        dataLines.push(line.slice(6));
+                    }
+                    else if (line.startsWith('data:')) {
+                        dataLines.push(line.slice(5));
+                    }
+                    // Ignore lines starting with ':' (comments/keepalive)
+                    // Ignore 'event:', 'id:', 'retry:' — we only use unnamed data events
+                }
+                if (dataLines.length === 0)
+                    continue;
+                const jsonStr = dataLines.join('\n');
+                try {
+                    const event = JSON.parse(jsonStr);
+                    yield event;
+                }
+                catch {
+                    // Non-JSON data line — skip (could be a keepalive or malformed chunk)
+                }
+            }
+        }
+        // Flush remaining buffer
+        if (buffer.trim()) {
+            const dataLines = [];
+            for (const line of buffer.split('\n')) {
+                if (line.startsWith('data: '))
+                    dataLines.push(line.slice(6));
+                else if (line.startsWith('data:'))
+                    dataLines.push(line.slice(5));
+            }
+            if (dataLines.length > 0) {
+                try {
+                    const event = JSON.parse(dataLines.join('\n'));
+                    yield event;
+                }
+                catch {
+                    // Ignore incomplete final chunk
+                }
+            }
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+}

package/dist/types.d.ts

@@ -537,6 +537,48 @@ export interface PromptResponse {
         stepsExecuted: number;
     }>;
 }
+/** Text chunk from the LLM stream. Many of these per response. */
+export interface SSETextEvent {
+    type: 'text';
+    chunk: string;
+}
+/** A named output extracted from the stream when its </output> tag closes. One per output. */
+export interface SSEOutputEvent {
+    type: 'output';
+    name: string;
+    data: unknown;
+}
+/** Fired after each instruction step completes (multi-step mode). */
+export interface SSEStepCompleteEvent {
+    type: 'step_complete';
+    instructionIndex: number;
+    text: string;
+    toolCalls: Array<{
+        toolName: string;
+    }>;
+}
+/** Final event — includes all outputs, evaluation, and metadata. */
+export interface SSEDoneEvent {
+    type: 'done';
+    outputs?: Record<string, unknown>;
+    toolOutputs?: Record<string, unknown>;
+    evaluation?: unknown;
+    metadata?: unknown;
+}
+/** Non-fatal error during streaming. */
+export interface SSEErrorEvent {
+    type: 'error';
+    message: string;
+}
+/** Union of all SSE event types emitted by the /prompt streaming endpoint. */
+export type PromptSSEEvent = SSETextEvent | SSEOutputEvent | SSEStepCompleteEvent | SSEDoneEvent | SSEErrorEvent;
+/** Options for promptStream(). Extends PromptOptions but forces stream: true. */
+export interface PromptStreamOptions extends Omit<PromptOptions, 'stream'> {
+    /** Timeout in milliseconds for the overall stream (default: 120000). */
+    streamTimeout?: number;
+    /** Abort signal for cancellation. */
+    signal?: AbortSignal;
+}
 export interface TestResponse {
     timestamp: string;
     ip: string;
@@ -624,6 +666,14 @@ export interface MemorizeOptions {
     skipDualWrite?: boolean;
     /** If true, skip property selection step. */
     skipPropertySelection?: boolean;
+    /** Phone number for entity scoping. */
+    phoneNumber?: string;
+    /** Postal code for entity scoping. */
+    postalCode?: string;
+    /** Device ID for entity scoping. */
+    deviceId?: string;
+    /** Content ID for entity scoping. */
+    contentId?: string;
 }
 /** @deprecated Use MemorizeOptions instead. */
 export type MemorizeProOptions = MemorizeOptions;
@@ -632,6 +682,8 @@ export interface SmartRecallOptions {
     query: string;
     /** Compatibility alias for query. */
     message?: string;
+    /** Retrieval mode. "fast" skips reflection (~500ms, 1 credit). "deep" enables reflection + answer (~10-20s, 2 credits). Default: "deep". */
+    mode?: 'fast' | 'deep';
     /** Max results to return (default: 10). */
     limit?: number;
     /** Minimum similarity score threshold. */
@@ -648,6 +700,22 @@ export interface SmartRecallOptions {
     websiteUrl?: string;
     /** Entity type filter (e.g. 'Contact', 'Company'). */
     type?: string;
+    /** Phone number for entity scoping. */
+    phoneNumber?: string;
+    /** Phone number (snake_case alias). */
+    phone_number?: string;
+    /** Postal code for entity scoping. */
+    postalCode?: string;
+    /** Postal code (snake_case alias). */
+    postal_code?: string;
+    /** Device ID for entity scoping. */
+    deviceId?: string;
+    /** Device ID (snake_case alias). */
+    device_id?: string;
+    /** Content ID for entity scoping. */
+    contentId?: string;
+    /** Content ID (snake_case alias). */
+    content_id?: string;
     /** Custom key name — for entity types with domain-specific unique IDs. */
     customKeyName?: string;
     /** Custom key value — the unique identifier value. */
@@ -682,6 +750,10 @@ export interface SmartRecallOptions {
      * In fast_mode, defaults to 10. Set to 0 to disable (strict score cutoff).
      */
     min_results?: number;
+    /** Apply exponential recency decay to scores. Recent memories rank higher. */
+    prefer_recent?: boolean;
+    /** Half-life in days for recency decay (default: 90). A memory this many days old has its score multiplied by ~0.37. */
+    recency_half_life_days?: number;
     /** Metadata filters for narrowing results. */
     filters?: Record<string, unknown>;
 }
@@ -710,8 +782,18 @@ export interface RecallOptions {
     customKeyName?: string;
     /** Custom key value — the unique identifier value. */
     customKeyValue?: string;
+    /** Phone number for entity scoping. */
+    phoneNumber?: string;
+    /** Postal code for entity scoping. */
+    postalCode?: string;
+    /** Device ID for entity scoping. */
+    deviceId?: string;
+    /** Content ID for entity scoping. */
+    contentId?: string;
     /** Additional filters. */
     filters?: Record<string, unknown>;
+    /** Scope results to specific collections by ID. */
+    collectionIds?: string[];
     /** Compatibility alias for a single collection name. */
     collectionName?: string;
     /** Compatibility alias for collection scoping by name. */
@@ -811,6 +893,45 @@ export interface BatchMemorizeRecord {
     timestamp?: string;
     speaker?: string;
 }
+export interface GetPropertiesOptions {
+    /** Contact email. */
+    email?: string;
+    /** Company website URL. */
+    websiteUrl?: string;
+    /** Website URL (snake_case alias). */
+    website_url?: string;
+    /** CRM record ID. */
+    recordId?: string;
+    /** CRM record ID (snake_case alias). */
+    record_id?: string;
+    /** Entity type. */
+    type?: string;
+    /** Custom CRM key field name. */
+    customKeyName?: string;
+    /** Custom CRM key field value. */
+    customKeyValue?: string;
+    /** Filter to specific properties by name. */
+    propertyNames?: string[];
+    /** Include collection schema descriptions (default: true). */
+    includeDescriptions?: boolean;
+    /** Only return non-empty properties (default: false). */
+    nonEmpty?: boolean;
+}
+export interface PropertyItem {
+    name: string;
+    value: unknown;
+    type?: string;
+    description?: string;
+    /** true = replaceable (set), false = append-only (push only). */
+    update?: boolean;
+    collectionId?: string;
+    collectionName?: string;
+}
+export interface GetPropertiesResponse {
+    recordId: string;
+    type: string;
+    properties: PropertyItem[];
+}
 export interface SmartDigestOptions {
     /** CRM record ID */
     record_id?: string;
@@ -840,6 +961,14 @@ export interface SmartDigestOptions {
     include_memories?: boolean;
     /** Include memories (camelCase alias). */
     includeMemories?: boolean;
+    /** Phone number for entity scoping. */
+    phoneNumber?: string;
+    /** Postal code for entity scoping. */
+    postalCode?: string;
+    /** Device ID for entity scoping. */
+    deviceId?: string;
+    /** Content ID for entity scoping. */
+    contentId?: string;
 }
 export interface SmartDigestResponse {
     success: boolean;
@@ -961,6 +1090,223 @@ export interface SearchResponse extends Array<SearchResultItem> {
 }
 /** @deprecated Use SearchResponse instead. */
 export type ExportResponse = SearchResponse;
+export interface UpdatePropertyOptions {
+    /** Target record ID. */
+    recordId: string;
+    /** Entity type (default: 'contact'). */
+    type?: string;
+    /** Property to update. Required for property updates (mutually exclusive with memoryId+text). */
+    propertyName?: string;
+    /** New property value. Required unless using array operations. */
+    propertyValue?: any;
+    /** Collection ID for the property. */
+    collectionId?: string;
+    /** Confidence score for this value. */
+    confidence?: number;
+    /** Reason for the change (logged in property history). */
+    reason?: string;
+    /** Who made the change (auto-set from API key if omitted). */
+    updatedBy?: string;
+    /** Idempotency key to prevent duplicate writes. */
+    idempotencyKey?: string;
+    /** Optimistic concurrency guard. If set, returns 409 if the record's current version differs. */
+    expectedVersion?: number;
+    /** Append items to an array property. With `unique: true`, skips duplicates. */
+    arrayPush?: {
+        items: any[];
+        unique?: boolean;
+    };
+    /** Remove items from an array property by value or index. */
+    arrayRemove?: {
+        items?: any[];
+        indices?: number[];
+    };
+    /** Update matching objects inside an array property. */
+    arrayPatch?: {
+        match: Record<string, any>;
+        set: Record<string, any>;
+    };
+    /** Freeform memory UUID to edit. */
+    memoryId?: string;
+    /** New text for the freeform memory. */
+    text?: string;
+}
+export interface UpdateResult {
+    success: boolean;
+    previousValue?: any;
+    newValue: any;
+    version?: number;
+    stores: {
+        snapshot: 'updated' | 'skipped';
+        lancedb: 'updated' | 'skipped';
+        freeform: 'updated' | 'skipped';
+    };
+}
+export interface BulkUpdateOptions {
+    /** Target record ID. */
+    recordId: string;
+    /** Entity type (default: 'contact'). */
+    type?: string;
+    /** Array of property updates. */
+    updates: Array<{
+        propertyName: string;
+        propertyValue: any;
+        collectionId?: string;
+        confidence?: number;
+    }>;
+    /** Who made the changes. */
+    updatedBy?: string;
+    /** Idempotency key to prevent duplicate writes. */
+    idempotencyKey?: string;
+    /** Optimistic concurrency guard. Checked before any writes; 409 if mismatch. */
+    expectedVersion?: number;
+}
+export interface BulkUpdateResult {
+    success: boolean;
+    results: Array<{
+        propertyName: string;
+        previousValue?: any;
+        newValue: any;
+        status: 'updated' | 'failed';
+        error?: string;
+    }>;
+    version?: number;
+}
+export interface PropertyHistoryOptions {
+    /** Target record ID. */
+    recordId: string;
+    /** Filter to a specific property. */
+    propertyName?: string;
+    /** ISO-8601 lower bound. */
+    from?: string;
+    /** ISO-8601 upper bound. */
+    to?: string;
+    /** Max entries to return (default: 50, max: 200). */
+    limit?: number;
+    /** Pagination cursor from previous response. */
+    nextToken?: string;
+}
+export interface PropertyHistoryEntry {
+    entryId: string;
+    propertyName: string;
+    propertyValue: any;
+    collectionId: string;
+    collectionName?: string;
+    updatedBy: string;
+    createdAt: string;
+    source?: string;
+}
+export interface PropertyHistoryResult {
+    entries: PropertyHistoryEntry[];
+    nextToken?: string;
+}
+export interface QueryPropertiesOptions {
+    /** Which property to search across. */
+    propertyName: string;
+    /** Natural language query. */
+    query: string;
+    /** Limit to single record. */
+    recordId?: string;
+    /** Entity type filter (default: 'contact'). */
+    type?: string;
+    /** Max results (default: 100, max: 200). */
+    limit?: number;
+}
+export interface QueryPropertiesResult {
+    matches: Array<{
+        recordId: string;
+        propertyValue: any;
+        matchReason: string;
+    }>;
+    processedCount: number;
+    totalAvailable: number;
+    truncated: boolean;
+    capMessage?: string;
+}
+export interface DeleteMemoriesOptions {
+    /** Memory UUIDs to delete. */
+    ids?: string[];
+    /** CRM identifiers for scoping. */
+    crmKeys?: {
+        recordId?: string;
+        email?: string;
+        websiteUrl?: string;
+    };
+    /** ISO date — delete memories older than this. */
+    olderThan?: string;
+}
+export interface DeleteRecordOptions {
+    /** Record ID to delete. */
+    recordId: string;
+    /** Entity type (required). */
+    type: string;
+    /** CRM identifiers for additional LanceDB filtering. */
+    crmKeys?: {
+        recordId?: string;
+        email?: string;
+        websiteUrl?: string;
+    };
+    /** Reason for deletion. */
+    reason?: string;
+    /** Who performed the deletion. */
+    performedBy?: string;
+}
+export interface DeletionResult {
+    success: boolean;
+    deletedCount?: number;
+    hardDeleteAt?: string;
+}
+export interface CancelDeletionOptions {
+    /** Record ID to restore. */
+    recordId: string;
+    /** Entity type (default: 'contact'). */
+    type?: string;
+    /** Who performed the restoration. */
+    performedBy?: string;
+}
+export interface CancelDeletionResult {
+    success: boolean;
+    restoredCounts: {
+        snapshot: 'restored' | 'already_gone';
+        freeform: 'restored' | 'already_gone';
+        lancedb: 'restored' | 'already_gone';
+    };
+    warning?: string;
+}
+/** Comparison operators for deterministic property filters. */
+export type FilterOperator = 'equals' | 'notEquals' | 'contains' | 'gt' | 'lt' | 'gte' | 'lte' | 'exists' | 'isEmpty';
+export interface PropertyFilterCondition {
+    /** Property to filter on. */
+    propertyName: string;
+    /** Comparison operator. */
+    operator: FilterOperator;
+    /** Value to compare against. Not needed for 'exists'/'isEmpty'. */
+    value?: any;
+}
+export interface FilterByPropertyOptions {
+    /** Entity type (default: 'contact'). */
+    type?: string;
+    /** Filter conditions. */
+    conditions: PropertyFilterCondition[];
+    /** Combine conditions with AND (default) or OR. */
+    logic?: 'AND' | 'OR';
+    /** Max results (default: 50, max: 200). */
+    limit?: number;
+    /** Pagination cursor. */
+    nextToken?: string;
+}
+export interface FilterByPropertyResult {
+    records: Array<{
+        recordId: string;
+        type: string;
+        matchedProperties: Record<string, any>;
+        lastUpdatedAt?: number;
+    }>;
+    totalMatched: number;
+    nextToken?: string;
+}
+/** Webhook event types fired by memory CRUD operations. */
+export type MemoryWebhookEvent = 'memory.property.updated' | 'memory.properties.bulk_updated' | 'memory.updated' | 'memory.deleted' | 'memory.record.deleted' | 'memory.record.deletion_cancelled';
 export interface EvaluateMemorizationOptions {
     /** Collection to evaluate against. */
     collectionId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@personize/sdk",
-    "version": "0.6.4",
+    "version": "0.6.5",
     "description": "Official Personize SDK",
     "main": "dist/index.js",
     "types": "dist/index.d.ts",