@personize/sdk 0.6.1 → 0.6.4

package/README.md

@@ -134,7 +134,7 @@ const byok = await client.ai.prompt({
     model: 'anthropic/claude-sonnet-4-20250514',
     provider: 'openrouter',
 });
-// BYOK billing: time-based (10 credits base + 10/extra minute) instead of per-token
+// BYOK billing: flat 5 credits/call — no per-token charge, you pay your provider directly
 // Without BYOK, model/provider are rejected — use tier to control quality level
 
 // Multi-step instructions with evaluation
@@ -216,6 +216,32 @@ const fast = await client.memory.smartRecall({
     // 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
+// Use customKeyName/customKeyValue when email or websiteUrl don't apply.
+// The recordId is generated deterministically from orgId + type + key — same key always resolves to the same record.
+await client.memory.memorize({
+    content: 'Student enrolled in Advanced AI course. GPA 3.8, Dean\'s List.',
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+    enhanced: true,
+});
+
+// More examples: LinkedIn profiles, web pages, code files, products...
+await client.memory.memorize({ content: '...', type: 'Person',  customKeyName: 'linkedinUrl',  customKeyValue: 'https://linkedin.com/in/johndoe' });
+await client.memory.memorize({ content: '...', type: 'Webpage', customKeyName: 'pageUrl',      customKeyValue: 'https://docs.example.com/api/auth' });
+await client.memory.memorize({ content: '...', type: 'File',    customKeyName: 'filePath',     customKeyValue: 'src/auth/oauth.ts' });
+await client.memory.memorize({ content: '...', type: 'Product', customKeyName: 'sku',          customKeyValue: 'PRD-X100-BLK' });
+
+// Recall by the same custom key — no need to know the recordId
+const student = await client.memory.smartRecall({
+    query: 'What courses is this student enrolled in?',
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+    fast_mode: true,
+});
+
 // Direct recall — DynamoDB lookup: properties + freeform memories (no AI, type required)
 const direct = await client.memory.recall({
     query: 'What do we know about Acme?',
@@ -225,7 +251,15 @@ const direct = await client.memory.recall({
 // direct.data.memories — structured properties from Snapshot
 // direct.data.freeformMemories — AI-extracted memories from Freeform table
 
-// Search/filter records by property conditions
+// Direct recall by custom key
+const student = await client.memory.recall({
+    query: 'Academic record',
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+});
+
+// Search/filter records by property conditions — works with any type value
 const found = await client.memory.search({
     groups: [{
         conditions: [{ property: 'company-name', operator: 'equals', value: 'Acme Corp' }],
@@ -234,6 +268,64 @@ const found = await client.memory.search({
     pageSize: 50,
 });
 
+// Search across a custom entity type
+const deansList = await client.memory.search({
+    type: 'Student',
+    returnRecords: true,
+    groups: [{
+        conditions: [{ property: 'gpa', operator: 'GTE', value: 3.5 }],
+    }],
+});
+
+// Access property values: records[recordId][propertyName].value (plain string)
+for (const [recordId, props] of Object.entries(found.data?.records ?? {})) {
+    const email = props['email']?.value;           // plain string — whatever was stored
+    const company = props['company-name']?.value;
+    console.log(`${recordId}: ${email} at ${company}`);
+}
+// Note: 'email' and 'company-name' must match the property names in your collection definition
+
+// --- Advanced Search Patterns ---
+
+// Key-only lookup: find a record by email without needing property conditions
+const byEmail = await client.memory.search({
+    email: 'sarah@acme.com',
+    returnRecords: true,
+});
+
+// Key-only lookup: find a record by custom key (no groups needed)
+const byStudentNumber = await client.memory.search({
+    type: 'Student',
+    customKeyName: 'studentNumber',
+    customKeyValue: 'S-2024-1234',
+    returnRecords: true,
+});
+
+// Secondary key: find Students where email is a secondary attribute (not the primary key)
+// Works because memorize stores all CRM keys on every LanceDB row
+const studentByEmail = await client.memory.search({
+    type: 'Student',
+    email: 'alice@university.edu',
+    returnRecords: true,
+});
+
+// Cross-type search: find ALL records with this email across ALL entity types
+// Returns Contacts, Students, Employees — whatever has this email
+const crossType = await client.memory.search({
+    email: 'john@acme.com',
+    returnRecords: true,
+});
+
+// Property-value lookup: find records by a stored property (e.g. LinkedIn URL)
+// Use this when the lookup key is a property value, not a CRM identifier
+const byLinkedIn = await client.memory.search({
+    type: 'Contact',
+    returnRecords: true,
+    groups: [{
+        conditions: [{ property: 'linkedin_url', operator: 'EQ', value: 'https://linkedin.com/in/johndoe' }],
+    }],
+});
+
 // Batch sync — unified call with per-property extractMemories control
 // IMPORTANT: Set extractMemories: true on rich text fields (notes, transcripts, descriptions)
 // to enable AI extraction and semantic search. Without it, only structured storage occurs.
@@ -241,6 +333,9 @@ await client.memory.memorizeBatch({
     source: 'Hubspot',
     mapping: {
         entityType: 'contact',
+        // email: 'email' means "use the 'email' field from each row as the contact identifier"
+        // The value must match the key name in your rows array (e.g., row.email)
+        // Use websiteUrl instead for Company records, or recordId for direct ID matching
         email: 'email',
         properties: {
             email:     { sourceField: 'email',    collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
@@ -253,6 +348,25 @@ await client.memory.memorizeBatch({
     ],
 });
 
+// Batch sync with custom keys — for non-Contact/Company entity types
+await client.memory.memorizeBatch({
+    source: 'University DB',
+    mapping: {
+        entityType: 'Student',
+        customKeyName: 'studentNumber',   // the identifier name
+        customKey: 'student_id',          // source field in rows holding the value
+        properties: {
+            full_name: { sourceField: 'name',   collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
+            gpa:       { sourceField: 'gpa',    collectionId: 'col_std', collectionName: 'Standard', extractMemories: false },
+            notes:     { sourceField: 'notes',  collectionId: 'col_gen', collectionName: 'Generated', extractMemories: true },
+        },
+    },
+    rows: [
+        { student_id: 'S-2024-1234', name: 'Alice Chen', gpa: '3.8', notes: 'Dean\'s List, AI research focus' },
+        { student_id: 'S-2024-5678', name: 'Bob Park', gpa: '3.5', notes: 'Full-stack internship at Stripe' },
+    ],
+});
+
 // Smart memory digest — compiled context for an entity
 const digest = await client.memory.smartDigest({
     email: 'john@acme.com',
@@ -325,27 +439,29 @@ console.log(evaluation.data.summary.propertiesOptimized);
 
 | Tier | Input Credits/1K tokens | Output Credits/1K tokens | Best For |
 | :--- | :--- | :--- | :--- |
-| `basic` | 0.2 | 0.4 | High-volume, simple tasks |
-| `pro` | 0.5 | 1.0 | Balanced quality & cost (default) |
-| `ultra` | 1.0 | 2.5 | Complex reasoning, highest quality |
+| `basic` | 1.0 | 2.0 | High-volume, simple tasks |
+| `pro` | 1.0 | 3.0 | Balanced quality & cost (default) |
+| `ultra` | 1.0 | 5.0 | Complex reasoning, highest quality |
 
 ### Memorize Tiers
 
 | Tier | Credits/1K tokens | Best For |
 | :--- | :--- | :--- |
-| `basic` | 1.0 | Bulk imports, simple data |
-| `pro` | 2.5 | General use (default) |
-| `pro_fast` | 3.5 | Pro quality, lower latency |
-| `ultra` | 7.0 | Maximum extraction quality |
+| `basic` | 1 | Bulk imports, simple data |
+| `pro` | 3 | General use (default) |
+| `pro_fast` | 5 | Pro quality, lower latency |
+| `ultra` | 12 | Maximum extraction quality |
 
 ### Retrieval (Recall & Smart Guidelines)
 
 | Operation | Mode | Credits/Call |
 | :--- | :--- | :--- |
-| Smart Recall | `fast_mode: true` | 0.1 |
-| Smart Recall | `fast_mode: false` (deep) | 0.2 |
-| Smart Guidelines | `mode: 'fast'` | 0.1 |
-| Smart Guidelines | `mode: 'deep'` | 0.5 |
+| Smart Recall | `fast_mode: true` | 1 |
+| Smart Recall | `fast_mode: false` (deep) | 1 |
+| 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.
 
 1 credit = $0.01.
 
@@ -353,7 +469,7 @@ console.log(evaluation.data.summary.propertiesOptimized);
 
 ### BYOK (Bring Your Own Key)
 
-Pro and Enterprise plans can pass their own API key. Billing switches to time-based: **10 credits base + 10 credits per additional minute**.
+Pro and Enterprise plans can pass their own API key. Billing switches to a flat **5 credits per call** (no per-token charge — you pay your provider directly).
 
 When using BYOK, you **must** provide both `model` and `provider`. Without BYOK, `model` and `provider` are rejected — use `tier` to control quality level.
 
@@ -378,7 +494,7 @@ await client.ai.prompt({
 - `openrouterApiKey` without `model`/`provider` → `400 model and provider required`
 - BYOK on a plan that doesn't allow it → `403 byok_not_allowed`
 
-Response metadata includes `byok: true` and `creditsCharged` reflecting time-based billing.
+Response metadata includes `byok: true` and `creditsCharged` reflecting the flat 5-credit charge.
 
 ## Best Practices: Query Crafting for smartRecall
 
@@ -427,7 +543,23 @@ const client = new Personize({
 });
 ```
 
-## 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, 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, AgentRunOptions, AgentResponse, MemorizeOptions, SmartRecallOptions, RecallOptions, RecallResponse, SearchOptions, SearchResponse, BatchMemorizeOptions, SmartDigestOptions, SmartDigestResponse, EvaluateMemorizationOptions, EvaluateMemorizationResponse } from './types';
 export declare class Personize {
     private client;
     private _organizationId?;
@@ -8,6 +8,26 @@ export declare class Personize {
     constructor(config: PersonizeConfig);
     private resolveIdentity;
     private getOrganizationId;
+    private normalizePropertyOptions;
+    private inferEntityTypeFromKeys;
+    private listAllCollections;
+    private resolveCollectionIdsByName;
+    private normalizeCollectionCreatePayload;
+    private attachArrayMetadata;
+    private normalizeGuidelinesListResponse;
+    private normalizeCollectionsListResponse;
+    private normalizePromptOptions;
+    private normalizeMemorizeOptions;
+    private normalizeSmartRecallOptions;
+    private isLegacyRecallRequest;
+    private normalizeLegacyRecallToSmartRecall;
+    private normalizeRecallOptions;
+    private buildSearchGroupsFromFilters;
+    private normalizeSearchRequest;
+    private normalizeSearchResponse;
+    private normalizeRecallResponse;
+    private isBatchRecordProperty;
+    private memorizeBatchFromRecords;
     /**
      * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
      */
@@ -111,11 +131,11 @@ export declare class Personize {
          * POST /api/v1/smart-recall — Advanced recall with reflection (RAG).
          * Supports reflection loops for improved coverage, answer generation, and entity scoping.
          */
-        smartRecall: (data: SmartRecallOptions) => Promise<ApiResponse>;
+        smartRecall: (data: SmartRecallOptions) => Promise<ApiResponse<RecallResponse>>;
         /**
          * POST /api/v1/recall — Direct memory lookup (no reflection).
          */
-        recall: (data: RecallOptions) => Promise<ApiResponse>;
+        recall: (data: RecallOptions) => Promise<ApiResponse<RecallResponse>>;
         /**
          * POST /api/v1/search — Filter and search records by property conditions.
          * Returns matching record IDs with optional property values and memories.

package/dist/client.js

@@ -26,7 +26,11 @@ class Personize {
                 if (options?.excludeTags)
                     params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
                 const response = await this.client.get('/api/v1/guidelines', { params });
-                return response.data;
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeGuidelinesListResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * GET /api/v1/guidelines/:id/structure — Get guideline headings
@@ -100,13 +104,18 @@ class Personize {
                 if (options?.excludeTags)
                     params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
                 const response = await this.client.get('/api/v1/collections', { params });
-                return response.data;
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeCollectionsListResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/collections — Create a new property collection
              */
             create: async (payload) => {
-                const response = await this.client.post('/api/v1/collections', payload);
+                const normalizedPayload = await this.normalizeCollectionCreatePayload(payload);
+                const response = await this.client.post('/api/v1/collections', normalizedPayload);
                 return response.data;
             },
             /**
@@ -156,7 +165,8 @@ class Personize {
              * Use `memorize` to auto-save outputs and tool results to memory.
              */
             prompt: async (options) => {
-                const response = await this.client.post('/api/v1/prompt', options);
+                const normalizedOptions = this.normalizePromptOptions(options);
+                const response = await this.client.post('/api/v1/prompt', normalizedOptions);
                 return response.data;
             },
         };
@@ -201,7 +211,35 @@ class Personize {
              * Performs structured property extraction and free-form memory creation.
              */
             memorize: async (data) => {
-                const response = await this.client.post('/api/v1/memorize', data);
+                if (data.properties && Object.keys(data.properties).length > 0) {
+                    return this.memorizeBatchFromRecords({
+                        source: 'SDK memorize compatibility',
+                        enhanced: data.enhanced,
+                        records: [{
+                                content: data.content,
+                                email: data.email,
+                                website_url: data.website_url,
+                                record_id: data.record_id,
+                                type: data.type,
+                                customKeyName: data.customKeyName,
+                                customKeyValue: data.customKeyValue,
+                                collectionId: data.collectionIds?.[0],
+                                collectionName: data.collectionName,
+                                properties: data.properties,
+                                tags: data.tags,
+                                enhanced: data.enhanced,
+                                timestamp: data.timestamp,
+                                speaker: data.speaker,
+                            }],
+                        mapping: {
+                            entityType: data.type || 'Record',
+                            properties: {},
+                        },
+                        rows: [],
+                    });
+                }
+                const normalizedData = await this.normalizeMemorizeOptions(data);
+                const response = await this.client.post('/api/v1/memorize', normalizedData);
                 return response.data;
             },
             /**
@@ -209,23 +247,63 @@ class Personize {
              * Supports reflection loops for improved coverage, answer generation, and entity scoping.
              */
             smartRecall: async (data) => {
-                const response = await this.client.post('/api/v1/smart-recall', data);
-                return response.data;
+                const normalizedData = this.normalizeSmartRecallOptions(data);
+                const response = await this.client.post('/api/v1/smart-recall', normalizedData);
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeRecallResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/recall — Direct memory lookup (no reflection).
              */
             recall: async (data) => {
-                const response = await this.client.post('/api/v1/recall', data);
-                return response.data;
+                if (this.isLegacyRecallRequest(data)) {
+                    const compatPayload = this.normalizeLegacyRecallToSmartRecall(data);
+                    const response = await this.client.post('/api/v1/smart-recall', compatPayload);
+                    const responseData = response.data;
+                    if (responseData?.data) {
+                        responseData.data = this.normalizeRecallResponse(responseData.data);
+                    }
+                    return responseData;
+                }
+                const normalizedData = this.normalizeRecallOptions(data);
+                const response = await this.client.post('/api/v1/recall', normalizedData);
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeRecallResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/search — Filter and search records by property conditions.
              * Returns matching record IDs with optional property values and memories.
              */
             search: async (data) => {
-                const response = await this.client.post('/api/v1/search', data);
-                return response.data;
+                const normalizedRequest = await this.normalizeSearchRequest(data);
+                if (normalizedRequest.mode === 'smartRecall') {
+                    const response = await this.client.post('/api/v1/smart-recall', normalizedRequest.payload);
+                    const responseData = response.data;
+                    if (responseData?.data) {
+                        const recallData = this.normalizeRecallResponse(responseData.data);
+                        responseData.data = this.attachArrayMetadata([...(recallData || [])], {
+                            recordIds: [],
+                            totalMatched: recallData?.length || 0,
+                            page: 1,
+                            pageSize: recallData?.length || 0,
+                            totalPages: 1,
+                            results: recallData ? [...recallData] : [],
+                        });
+                    }
+                    return responseData;
+                }
+                const response = await this.client.post('/api/v1/search', normalizedRequest.payload);
+                const responseData = response.data;
+                if (responseData?.data) {
+                    responseData.data = this.normalizeSearchResponse(responseData.data);
+                }
+                return responseData;
             },
             /**
              * POST /api/v1/batch-memorize — Unified batch sync with per-property extractMemories flag.
@@ -233,6 +311,9 @@ class Personize {
              * Properties without it (or false) are stored as structured data only.
              */
             memorizeBatch: async (data) => {
+                if (data.records?.length) {
+                    return this.memorizeBatchFromRecords(data);
+                }
                 const { organizationId, userId } = await this.resolveIdentity();
                 const response = await this.client.post('/api/v1/batch-memorize', {
                     ...data,
@@ -312,6 +393,387 @@ class Personize {
         const { organizationId } = await this.resolveIdentity();
         return organizationId;
     }
+    normalizePropertyOptions(options) {
+        if (!options)
+            return undefined;
+        return Array.isArray(options) ? options.join(',') : options;
+    }
+    inferEntityTypeFromKeys(input) {
+        if (input.primaryKeyField === 'email' || input.email)
+            return 'Contact';
+        if (input.primaryKeyField === 'website' || input.primaryKeyField === 'website_url' || input.website_url || input.websiteUrl) {
+            return 'Company';
+        }
+        return undefined;
+    }
+    async listAllCollections() {
+        const collections = [];
+        let nextToken;
+        do {
+            const response = await this.client.get('/api/v1/collections', {
+                params: {
+                    limit: 100,
+                    nextToken,
+                    summary: 'true',
+                },
+            });
+            const data = response.data?.data;
+            for (const action of data?.actions ?? []) {
+                const payload = action?.payload ?? {};
+                if (payload.collectionId && payload.collectionName) {
+                    collections.push({
+                        collectionId: String(payload.collectionId),
+                        collectionName: String(payload.collectionName),
+                    });
+                }
+            }
+            nextToken = data?.nextToken;
+        } while (nextToken);
+        return collections;
+    }
+    async resolveCollectionIdsByName(names) {
+        if (!names?.length)
+            return undefined;
+        const normalizedNames = names.map((name) => name.trim().toLowerCase()).filter(Boolean);
+        if (!normalizedNames.length)
+            return undefined;
+        const collections = await this.listAllCollections();
+        const ids = normalizedNames.map((target) => {
+            const match = collections.find((collection) => collection.collectionName.toLowerCase() === target);
+            return match?.collectionId;
+        }).filter((value) => Boolean(value));
+        return ids.length ? Array.from(new Set(ids)) : undefined;
+    }
+    async normalizeCollectionCreatePayload(payload) {
+        const normalizedProperties = payload.properties?.map((property) => ({
+            ...property,
+            options: this.normalizePropertyOptions(property.options),
+            update: property.update ?? (property.updateSemantics ? property.updateSemantics !== 'append' : undefined),
+        }));
+        return {
+            collectionName: payload.collectionName || payload.name || '',
+            collectionId: payload.collectionId || payload.slug,
+            definition: payload.definition || payload.description,
+            entityType: payload.entityType || this.inferEntityTypeFromKeys({ primaryKeyField: payload.primaryKeyField }),
+            properties: normalizedProperties,
+            status: payload.status,
+        };
+    }
+    attachArrayMetadata(items, metadata) {
+        return Object.assign(items, metadata);
+    }
+    normalizeGuidelinesListResponse(data) {
+        if (!data?.actions)
+            return data;
+        const items = data.actions.map((action) => ({
+            id: action.id,
+            type: action.type,
+            slug: typeof action.payload.name === 'string' ? action.payload.name : undefined,
+            ...action.payload,
+        }));
+        return this.attachArrayMetadata(items, data);
+    }
+    normalizeCollectionsListResponse(data) {
+        if (!data?.actions)
+            return data;
+        const items = data.actions.map((action) => ({
+            id: action.id,
+            type: action.type,
+            name: action.payload.collectionName,
+            slug: action.payload.collectionId,
+            ...action.payload,
+        }));
+        return this.attachArrayMetadata(items, data);
+    }
+    normalizePromptOptions(options) {
+        if (!options.evaluationCriteria || options.evaluate) {
+            const { evaluationCriteria, ...rest } = options;
+            return rest;
+        }
+        const { evaluationCriteria, ...rest } = options;
+        return {
+            ...rest,
+            evaluate: {
+                criteria: evaluationCriteria,
+                serverSide: true,
+            },
+        };
+    }
+    async normalizeMemorizeOptions(data) {
+        const { collectionName, collectionNames, properties, ...rest } = data;
+        const requestedCollectionNames = [
+            ...(collectionNames || []),
+            ...(collectionName ? [collectionName] : []),
+        ];
+        const collectionIds = rest.collectionIds?.length
+            ? rest.collectionIds
+            : await this.resolveCollectionIdsByName(requestedCollectionNames);
+        return {
+            ...rest,
+            collectionIds,
+            properties,
+        };
+    }
+    normalizeSmartRecallOptions(data) {
+        const { message, collectionName, ...rest } = data;
+        return {
+            ...rest,
+            query: data.query || message || '',
+            collectionNames: data.collectionNames || (collectionName ? [collectionName] : undefined),
+        };
+    }
+    isLegacyRecallRequest(data) {
+        return Boolean(data.message ||
+            data.limit != null ||
+            data.collectionName ||
+            data.collectionNames?.length ||
+            !data.type);
+    }
+    normalizeLegacyRecallToSmartRecall(data) {
+        return {
+            query: data.query || data.message || '',
+            limit: data.limit,
+            email: data.email,
+            website_url: data.website_url,
+            websiteUrl: data.websiteUrl,
+            record_id: data.record_id,
+            recordId: data.recordId,
+            type: data.type || this.inferEntityTypeFromKeys({
+                email: data.email,
+                website_url: data.website_url,
+                websiteUrl: data.websiteUrl,
+            }),
+            customKeyName: data.customKeyName,
+            customKeyValue: data.customKeyValue,
+            filters: data.filters,
+            collectionNames: data.collectionNames || (data.collectionName ? [data.collectionName] : undefined),
+        };
+    }
+    normalizeRecallOptions(data) {
+        const { message, limit, collectionName, collectionNames, ...rest } = data;
+        return {
+            ...rest,
+            query: data.query || message || '',
+            type: data.type || this.inferEntityTypeFromKeys({
+                email: rest.email,
+                website_url: rest.website_url,
+                websiteUrl: rest.websiteUrl,
+            }),
+        };
+    }
+    buildSearchGroupsFromFilters(filters) {
+        if (!filters)
+            return undefined;
+        const conditions = Object.entries(filters)
+            .filter(([, value]) => value !== undefined)
+            .flatMap(([property, value]) => {
+            if (Array.isArray(value)) {
+                return value.map((item) => ({
+                    property,
+                    operator: 'contains',
+                    value: item,
+                }));
+            }
+            return [{
+                    property,
+                    operator: 'equals',
+                    value: value,
+                }];
+        });
+        return conditions.length ? [{ conditions }] : undefined;
+    }
+    async normalizeSearchRequest(data) {
+        const collectionNames = data.collectionNames || (data.collectionName ? [data.collectionName] : undefined);
+        if (data.query && !data.groups?.length) {
+            return {
+                mode: 'smartRecall',
+                payload: {
+                    query: data.query,
+                    limit: data.limit || data.pageSize,
+                    type: data.type,
+                    email: data.email,
+                    websiteUrl: data.websiteUrl,
+                    recordId: data.recordId,
+                    customKeyName: data.customKeyName,
+                    customKeyValue: data.customKeyValue,
+                    collectionNames,
+                    filters: data.filters,
+                },
+            };
+        }
+        const collectionIds = data.collectionIds?.length
+            ? data.collectionIds
+            : await this.resolveCollectionIdsByName(collectionNames);
+        return {
+            mode: 'search',
+            payload: {
+                type: data.type,
+                email: data.email,
+                websiteUrl: data.websiteUrl,
+                recordId: data.recordId,
+                customKeyName: data.customKeyName,
+                customKeyValue: data.customKeyValue,
+                collectionIds,
+                groups: data.groups || this.buildSearchGroupsFromFilters(data.filters),
+                pageSize: data.pageSize || data.limit,
+                page: data.page,
+                countOnly: data.countOnly,
+                returnRecords: data.returnRecords,
+                includeMemories: data.includeMemories,
+                dataSource: data.dataSource,
+            },
+        };
+    }
+    normalizeSearchResponse(data) {
+        if (!data)
+            return data;
+        const results = data.recordIds.map((recordId) => ({
+            recordId,
+            mainProperties: data.mainProperties?.[recordId],
+            record: data.records?.[recordId],
+            memories: data.memories?.[recordId],
+        }));
+        return this.attachArrayMetadata(results, {
+            ...data,
+            results: [...results],
+        });
+    }
+    normalizeRecallResponse(data) {
+        if (!data)
+            return undefined;
+        const source = Array.isArray(data) ? { results: data } : data;
+        const rawResults = Array.isArray(source.results)
+            ? source.results
+            : Array.isArray(source.memories)
+                ? source.memories
+                : [];
+        const results = rawResults.map((entry) => {
+            if (typeof entry !== 'object' || entry === null) {
+                return { content: String(entry), memory: String(entry) };
+            }
+            const record = entry;
+            const content = typeof record.content === 'string'
+                ? record.content
+                : typeof record.memory === 'string'
+                    ? record.memory
+                    : typeof record.text === 'string'
+                        ? record.text
+                        : undefined;
+            return {
+                ...record,
+                content,
+                memory: typeof record.memory === 'string' ? record.memory : content,
+            };
+        });
+        return this.attachArrayMetadata(results, {
+            ...(Array.isArray(data) ? {} : source),
+            results: [...results],
+        });
+    }
+    isBatchRecordProperty(value) {
+        return typeof value === 'object' && value !== null && 'value' in value;
+    }
+    async memorizeBatchFromRecords(data) {
+        const records = data.records || [];
+        if (!records.length) {
+            return { success: true, data: { memorized: 0 } };
+        }
+        const contentRecords = records.filter((record) => record.content);
+        for (const record of contentRecords) {
+            const normalizedMemorize = await this.normalizeMemorizeOptions({
+                content: String(record.content),
+                email: record.email,
+                website_url: record.website_url || record.websiteUrl,
+                record_id: record.record_id || record.recordId,
+                type: record.type,
+                customKeyName: record.customKeyName,
+                customKeyValue: record.customKeyValue,
+                tags: record.tags,
+                enhanced: record.enhanced ?? data.enhanced,
+                timestamp: record.timestamp,
+                speaker: record.speaker,
+                collectionNames: record.collectionName ? [record.collectionName] : undefined,
+                collectionIds: record.collectionId ? [record.collectionId] : undefined,
+            });
+            await this.memory.memorize(normalizedMemorize);
+        }
+        const structuredRecords = records.filter((record) => record.properties && Object.keys(record.properties).length > 0);
+        if (!structuredRecords.length) {
+            return { success: true, data: { memorized: contentRecords.length } };
+        }
+        const first = structuredRecords[0];
+        const entityType = first.type || this.inferEntityTypeFromKeys({
+            email: first.email,
+            website_url: first.website_url,
+            websiteUrl: first.websiteUrl,
+        }) || 'Record';
+        const mappingProperties = {};
+        const rows = structuredRecords.map((record) => {
+            const row = {};
+            if (record.email)
+                row.email = record.email;
+            if (record.website_url || record.websiteUrl)
+                row.website = record.website_url || record.websiteUrl;
+            if (record.record_id || record.recordId)
+                row.record_id = record.record_id || record.recordId;
+            if (record.customKeyValue)
+                row.custom_key = record.customKeyValue;
+            for (const [propertyName, rawProperty] of Object.entries(record.properties || {})) {
+                const property = this.isBatchRecordProperty(rawProperty)
+                    ? rawProperty
+                    : { value: rawProperty };
+                row[propertyName] = property.value;
+                if (!mappingProperties[propertyName]) {
+                    mappingProperties[propertyName] = {
+                        sourceField: propertyName,
+                        collectionId: property.collectionId || record.collectionId || '',
+                        collectionName: property.collectionName || record.collectionName || '',
+                        extractMemories: property.extractMemories,
+                    };
+                }
+            }
+            return row;
+        });
+        const unresolvedNames = Array.from(new Set(Object.values(mappingProperties)
+            .filter((property) => !property.collectionId && property.collectionName)
+            .map((property) => property.collectionName)));
+        const resolvedMap = new Map();
+        if (unresolvedNames.length) {
+            const collections = await this.listAllCollections();
+            for (const collection of collections) {
+                if (unresolvedNames.some((name) => name.toLowerCase() === collection.collectionName.toLowerCase())) {
+                    resolvedMap.set(collection.collectionName.toLowerCase(), collection.collectionId);
+                }
+            }
+        }
+        for (const property of Object.values(mappingProperties)) {
+            if (!property.collectionId && property.collectionName) {
+                property.collectionId = resolvedMap.get(property.collectionName.toLowerCase()) || '';
+            }
+            if (!property.collectionId || !property.collectionName) {
+                throw new Error('records shorthand requires collectionId/collectionName for each structured property');
+            }
+        }
+        const { organizationId, userId } = await this.resolveIdentity();
+        const response = await this.client.post('/api/v1/batch-memorize', {
+            source: data.source || 'SDK records shorthand',
+            tier: data.tier,
+            dryRun: data.dryRun,
+            chunkSize: data.chunkSize,
+            mapping: {
+                entityType,
+                email: rows.some((row) => row.email) ? 'email' : undefined,
+                website: rows.some((row) => row.website) ? 'website' : undefined,
+                customKeyName: first.customKeyName,
+                customKey: rows.some((row) => row.custom_key) ? 'custom_key' : undefined,
+                properties: mappingProperties,
+            },
+            rows,
+            orgId: organizationId,
+            userId,
+        });
+        return response.data;
+    }
     /**
      * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
      */

package/dist/types.d.ts

@@ -65,7 +65,18 @@ export interface GovernanceScope {
     /** Action/domain keywords that trigger inclusion (e.g., "email", "pricing", "deploy"). */
     triggerKeywords: string[];
 }
-export interface GuidelinesResponse {
+export interface GuidelineListItem {
+    id: string;
+    type: string;
+    name: string;
+    value: string;
+    /** Compatibility alias commonly used by setup scripts. */
+    slug?: string;
+    /** Auto-inferred governance scope (read-only). Present when the guideline has been analyzed. */
+    governanceScope?: GovernanceScope;
+    [key: string]: unknown;
+}
+export interface GuidelinesResponse extends Array<GuidelineListItem> {
     actions: Array<{
         id: string;
         type: string;
@@ -107,6 +118,8 @@ export interface GuidelineCreatePayload {
     description?: string;
     tags?: string[];
     secure?: boolean;
+    /** Compatibility alias used by some setup scripts. */
+    slug?: string;
 }
 /** @deprecated Use GuidelineCreatePayload instead. */
 export type VariableCreatePayload = GuidelineCreatePayload;
@@ -142,7 +155,17 @@ export interface GuidelineHistoryOptions {
 }
 /** @deprecated Use GuidelineHistoryOptions instead. */
 export type VariableHistoryOptions = GuidelineHistoryOptions;
-export interface CollectionsResponse {
+export interface CollectionListItem {
+    id: string;
+    type: string;
+    collectionName: string;
+    collectionId: string;
+    /** Compatibility aliases commonly used by setup scripts. */
+    name?: string;
+    slug?: string;
+    [key: string]: unknown;
+}
+export interface CollectionsResponse extends Array<CollectionListItem> {
     actions: Array<{
         id: string;
         type: string;
@@ -157,19 +180,34 @@ export interface CollectionsResponse {
     nextToken?: string;
 }
 export interface CollectionCreatePayload {
-    collectionName: string;
+    collectionName?: string;
     collectionId?: string;
     definition?: string;
     entityType?: string;
+    /** Compatibility alias for collectionName. */
+    name?: string;
+    /** Compatibility alias for collectionId. */
+    slug?: string;
+    /** Compatibility alias for definition. */
+    description?: string;
+    /** Accepted for compatibility; ignored unless the API supports it. */
+    icon?: string;
+    /** Accepted for compatibility; ignored unless the API supports it. */
+    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;
+        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';
     }>;
     status?: 'Active' | 'Deleted';
@@ -183,10 +221,13 @@ export interface CollectionUpdatePayload {
         propertyName?: string;
         systemName?: string;
         type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
-        options?: string;
+        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';
     }>;
     status?: 'Active' | 'Deleted';
@@ -413,6 +454,8 @@ export interface PromptOptions {
      * - `{ criteria: 'sales', serverSide: true }` — server-side with preset/custom criteria
      */
     evaluate?: PromptEvaluateConfig;
+    /** Compatibility alias for evaluate: { criteria, serverSide: true }. */
+    evaluationCriteria?: string;
     /**
      * Auto-memorize extracted outputs and/or captured tool results.
      * Requires at least one identifier (email, websiteUrl, or recordId).
@@ -551,12 +594,28 @@ export interface MemorizeOptions {
     email?: string;
     /** Website URL for CRM linking. */
     website_url?: string;
+    /** Entity type (e.g. 'Contact', 'Company', 'Student', 'Webpage'). */
+    type?: string;
+    /**
+     * Custom key name — for entity types with domain-specific unique IDs.
+     * Examples: 'studentNumber', 'linkedinUrl', 'employeeId', 'pageUrl', 'productSku'.
+     * Used with customKeyValue to identify the record when email/websiteUrl don't apply.
+     */
+    customKeyName?: string;
+    /** Custom key value — the unique identifier value (e.g. 'S12345', 'https://linkedin.com/in/johndoe'). */
+    customKeyValue?: string;
     /** Enable enhanced dual extraction (structured + free-form). */
     enhanced?: boolean;
+    /** Compatibility shorthand for structured property writes. */
+    properties?: Record<string, unknown | BatchMemorizeRecordProperty>;
     /** Tags for property selection. */
     tags?: string[];
     /** Limit extraction to specific collections. */
     collectionIds?: string[];
+    /** Compatibility alias for a single collection name; resolved client-side when possible. */
+    collectionName?: string;
+    /** Compatibility alias for collectionIds by name; resolved client-side when possible. */
+    collectionNames?: string[];
     /** Max properties to select for extraction. */
     max_properties?: number;
     /** If true, extract without persisting (dry run). */
@@ -571,6 +630,8 @@ export type MemorizeProOptions = MemorizeOptions;
 export interface SmartRecallOptions {
     /** Natural-language query. */
     query: string;
+    /** Compatibility alias for query. */
+    message?: string;
     /** Max results to return (default: 10). */
     limit?: number;
     /** Minimum similarity score threshold. */
@@ -587,10 +648,16 @@ export interface SmartRecallOptions {
     websiteUrl?: string;
     /** Entity type filter (e.g. 'Contact', 'Company'). */
     type?: string;
+    /** Custom key name — for entity types with domain-specific unique IDs. */
+    customKeyName?: string;
+    /** Custom key value — the unique identifier value. */
+    customKeyValue?: string;
     /** Scope results to specific collections by ID. */
     collectionIds?: string[];
     /** Scope results to specific collections by name (resolved server-side, case-insensitive). */
     collectionNames?: string[];
+    /** Compatibility alias for a single collection name. */
+    collectionName?: string;
     /** Return schema-enforced property values separately from free-form memories. */
     include_property_values?: boolean;
     /** Enable reflection loop to improve recall coverage (default: true). */
@@ -622,9 +689,13 @@ export interface SmartRecallOptions {
 export type RecallProOptions = SmartRecallOptions;
 export interface RecallOptions {
     /** Natural-language query. */
-    query: string;
-    /** Entity type (e.g. 'Contact', 'Company'). Required by the /recall endpoint. */
-    type: string;
+    query?: string;
+    /** Compatibility alias for query. */
+    message?: string;
+    /** Entity type (e.g. 'Contact', 'Company'). Required for direct /recall lookups. */
+    type?: string;
+    /** Compatibility alias retained for older advanced-recall call sites. */
+    limit?: number;
     /** CRM record ID for entity scoping. */
     record_id?: string;
     /** CRM record ID (camelCase alias). */
@@ -635,8 +706,39 @@ export interface RecallOptions {
     website_url?: string;
     /** Website URL (camelCase alias). */
     websiteUrl?: string;
+    /** Custom key name — for entity types with domain-specific unique IDs. */
+    customKeyName?: string;
+    /** Custom key value — the unique identifier value. */
+    customKeyValue?: string;
     /** Additional filters. */
     filters?: Record<string, unknown>;
+    /** Compatibility alias for a single collection name. */
+    collectionName?: string;
+    /** Compatibility alias for collection scoping by name. */
+    collectionNames?: string[];
+}
+export interface RecallResultItem {
+    content?: string;
+    memory?: string;
+    text?: string;
+    createdAt?: string;
+    score?: number;
+    recordId?: string;
+    type?: string;
+    email?: string;
+    website_url?: string;
+    website?: string;
+    company_name?: string;
+    name?: string;
+    properties?: Record<string, PropertyValue>;
+    metadata?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+export interface RecallResponse extends Array<RecallResultItem> {
+    results?: RecallResultItem[];
+    answer?: string;
+    query?: string;
+    [key: string]: unknown;
 }
 export interface BatchMemorizePropertyMapping {
     /** Source field name in the row data */
@@ -649,12 +751,19 @@ export interface BatchMemorizePropertyMapping {
     extractMemories?: boolean;
 }
 export interface BatchMemorizeMapping {
-    /** Entity type (e.g. 'contact', 'company') */
+    /** Entity type (e.g. 'contact', 'company', 'Student', 'Webpage') */
     entityType: string;
     /** Source field name that contains the email (e.g. 'email') */
     email?: string;
     /** Source field name that contains the website URL (e.g. 'company_website_url') */
     website?: string;
+    /**
+     * Custom key name — the identifier name for custom entity types (e.g. 'studentNumber', 'linkedinUrl').
+     * Use with `customKey` to specify which source field holds the identifier value.
+     */
+    customKeyName?: string;
+    /** Source field name that contains the custom key value (e.g. 'student_id', 'linkedin_url') */
+    customKey?: string;
     /** Run name for tracking (e.g. 'hubspot Sync (contact) - <uuid>') */
     runName?: string;
     /** Property mappings: target property name → mapping config */
@@ -662,17 +771,45 @@ export interface BatchMemorizeMapping {
 }
 export interface BatchMemorizeOptions {
     /** Source system label (e.g. 'Hubspot', 'Salesforce') */
-    source: string;
+    source?: string;
     /** Memorize tier: 'basic' | 'pro' | 'pro_fast' | 'ultra'. Default: 'pro'. */
     tier?: 'basic' | 'pro' | 'pro_fast' | 'ultra';
     /** Mapping configuration for the sync */
-    mapping: BatchMemorizeMapping;
+    mapping?: BatchMemorizeMapping;
     /** Array of source data rows (key-value objects matching sourceField names) */
-    rows: Record<string, unknown>[];
+    rows?: Record<string, unknown>[];
     /** If true, validate without writing (default: false) */
     dryRun?: boolean;
     /** Number of rows to process per chunk (default: 1) */
     chunkSize?: number;
+    /** Compatibility flag accepted and ignored when not needed. */
+    enhanced?: boolean;
+    /** Compatibility shorthand accepted by the SDK and normalized client-side. */
+    records?: BatchMemorizeRecord[];
+}
+export interface BatchMemorizeRecordProperty {
+    value: unknown;
+    extractMemories?: boolean;
+    collectionId?: string;
+    collectionName?: string;
+}
+export interface BatchMemorizeRecord {
+    content?: string;
+    email?: string;
+    website_url?: string;
+    websiteUrl?: string;
+    record_id?: string;
+    recordId?: string;
+    type?: string;
+    customKeyName?: string;
+    customKeyValue?: string;
+    collectionId?: string;
+    collectionName?: string;
+    properties?: Record<string, unknown | BatchMemorizeRecordProperty>;
+    tags?: string[];
+    enhanced?: boolean;
+    timestamp?: string;
+    speaker?: string;
 }
 export interface SmartDigestOptions {
     /** CRM record ID */
@@ -733,6 +870,8 @@ export interface SearchFilterGroup {
     conditions: SearchFilterCondition[];
 }
 export interface SearchOptions {
+    /** Compatibility shorthand for semantic search; routed client-side to smartRecall when groups are omitted. */
+    query?: string;
     /** Filter groups with conditions. To list all records, send one group with empty conditions. */
     groups?: SearchFilterGroup[];
     /** Entity type (e.g. 'Contact', 'Company'). */
@@ -743,12 +882,22 @@ export interface SearchOptions {
     websiteUrl?: string;
     /** Scope to a specific record ID. */
     recordId?: string;
+    /** Custom key name for custom entity types (e.g. 'studentNumber', 'linkedinUrl'). */
+    customKeyName?: string;
+    /** Custom key value (e.g. 'S-2024-1234'). Used with customKeyName to scope to a custom-keyed record. */
+    customKeyValue?: string;
     /** Scope to specific collections. */
     collectionIds?: string[];
+    /** Compatibility alias for a single collection name. */
+    collectionName?: string;
+    /** Compatibility alias for collection scoping by name. */
+    collectionNames?: string[];
     /** Page number (1-based, default: 1). */
     page?: number;
     /** Results per page (max 200, default: 50). */
     pageSize?: number;
+    /** Compatibility alias for pageSize. */
+    limit?: number;
     /** Return only totalMatched count. */
     countOnly?: boolean;
     /** Include property values per record. */
@@ -757,6 +906,8 @@ export interface SearchOptions {
     includeMemories?: boolean;
     /** Data source: 'lancedb' or 'snapshot' (default: 'lancedb'). */
     dataSource?: 'lancedb' | 'snapshot';
+    /** Compatibility shorthand filters; converted client-side to groups where possible. */
+    filters?: Record<string, unknown>;
 }
 /** @deprecated Use SearchOptions instead. */
 export type ExportOptions = SearchOptions;
@@ -766,7 +917,30 @@ export interface MemoryItem {
     score?: number;
     metadata?: Record<string, PropertyValue>;
 }
-export interface SearchResponse {
+export interface SearchResultItem {
+    recordId?: string;
+    mainProperties?: Record<string, string>;
+    record?: Record<string, {
+        value: PropertyValue;
+        collectionId: string;
+        collectionName?: string;
+    }>;
+    memories?: MemoryItem[];
+    content?: string;
+    memory?: string;
+    email?: string;
+    website_url?: string;
+    website?: string;
+    company_name?: string;
+    name?: string;
+    linkedin_url?: string;
+    phone_number?: string;
+    crm_id?: string;
+    lead_score?: number;
+    properties?: Record<string, PropertyValue>;
+    [key: string]: unknown;
+}
+export interface SearchResponse extends Array<SearchResultItem> {
     recordIds: string[];
     totalMatched: number;
     page: number;
@@ -782,6 +956,8 @@ export interface SearchResponse {
     mainProperties?: Record<string, Record<string, string>>;
     /** Free-form memories per record (when includeMemories is true). */
     memories?: Record<string, MemoryItem[]>;
+    /** Compatibility flattened result list derived client-side when possible. */
+    results?: SearchResultItem[];
 }
 /** @deprecated Use SearchResponse instead. */
 export type ExportResponse = SearchResponse;

package/package.json

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