@personize/sdk 0.7.1 → 0.7.3

package/dist/client.d.ts

@@ -27,6 +27,8 @@ export declare class Personize {
     private normalizeSearchResponse;
     private normalizeRecallResponse;
     private isBatchRecordProperty;
+    private hasRecordIdentity;
+    private buildContentValueWithMetadata;
     private memorizeBatchFromRecords;
     /**
      * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.
@@ -242,6 +244,32 @@ export declare class Personize {
          */
         segment: (data: SegmentOptions) => Promise<ApiResponse<SegmentResponse>>;
     };
+    smartRecallUnified: (data: import("./types").SmartRecallUnifiedOptions) => Promise<import("./types").ApiResponse<import("./types").SmartRecallUnifiedResponse>>;
+    rag: {
+        configure: (data: import("./types").ExternalRAGConfigOptions) => Promise<import("./types").ApiResponse<{
+            configured: boolean;
+        }>>;
+        search: (data: import("./types").ExternalRAGSearchOptions) => Promise<import("./types").ApiResponse<{
+            results: import("./types").ExternalRAGSearchResult[];
+        }>>;
+        test: () => Promise<import("./types").ApiResponse<{
+            healthy: boolean;
+            latencyMs: number;
+        }>>;
+    };
+    multimodal: {
+        memorize: (data: import("./types").MultimodalMemorizeOptions) => Promise<import("./types").ApiResponse<{
+            stored: boolean;
+        }>>;
+        search: (data: import("./types").MultimodalSearchOptions) => Promise<import("./types").ApiResponse<{
+            results: import("./types").MultimodalSearchResult[];
+        }>>;
+        status: () => Promise<import("./types").ApiResponse<{
+            enabled: boolean;
+            provider?: string;
+            model?: string;
+        }>>;
+    };
     evaluate: {
         /**
          * POST /api/v1/evaluate/memorization-accuracy — Run memorization accuracy evaluation.

package/dist/client.js

@@ -475,6 +475,41 @@ class Personize {
                 return response.data;
             },
         };
+        // ============ SmartRecall Unified ============
+        this.smartRecallUnified = async (data) => {
+            const response = await this.client.post('/api/v1/smart-recall-unified', data);
+            return response.data;
+        };
+        // ============ External RAG ============
+        this.rag = {
+            configure: async (data) => {
+                const response = await this.client.post('/api/v1/external-rag/config', data);
+                return response.data;
+            },
+            search: async (data) => {
+                const response = await this.client.post('/api/v1/external-rag/search', data);
+                return response.data;
+            },
+            test: async () => {
+                const response = await this.client.post('/api/v1/external-rag/test', {});
+                return response.data;
+            },
+        };
+        // ============ Multimodal ============
+        this.multimodal = {
+            memorize: async (data) => {
+                const response = await this.client.post('/api/v1/multimodal/memorize', data);
+                return response.data;
+            },
+            search: async (data) => {
+                const response = await this.client.post('/api/v1/multimodal/search', data);
+                return response.data;
+            },
+            status: async () => {
+                const response = await this.client.get('/api/v1/multimodal/status');
+                return response.data;
+            },
+        };
         this.evaluate = {
             /**
              * POST /api/v1/evaluate/memorization-accuracy — Run memorization accuracy evaluation.
@@ -895,21 +930,46 @@ class Personize {
     isBatchRecordProperty(value) {
         return typeof value === 'object' && value !== null && 'value' in value;
     }
+    hasRecordIdentity(record) {
+        return Boolean(record.email
+            || record.website_url || record.websiteUrl
+            || record.record_id || record.recordId
+            || record.customKeyValue);
+    }
+    buildContentValueWithMetadata(record) {
+        const content = String(record.content);
+        const metaParts = [];
+        if (record.speaker)
+            metaParts.push(`Speaker: ${record.speaker}`);
+        if (record.timestamp)
+            metaParts.push(`Date: ${record.timestamp}`);
+        if (!metaParts.length)
+            return content;
+        return `[${metaParts.join(' | ')}] ${content}`;
+    }
     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 batchRecords = [];
+        const fallbackRecords = [];
+        for (const record of records) {
+            const hasContent = Boolean(record.content && String(record.content).trim());
+            const hasProperties = Boolean(record.properties && Object.keys(record.properties).length > 0);
+            if (!hasContent && !hasProperties)
+                continue;
+            if (this.hasRecordIdentity(record)) {
+                batchRecords.push(record);
+            }
+            else if (hasContent) {
+                fallbackRecords.push(record);
+            }
+        }
+        const fallbackPromises = fallbackRecords.map(async (record) => {
             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,
@@ -917,20 +977,23 @@ class Personize {
                 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 } };
+            return this.memory.memorize(normalizedMemorize);
+        });
+        if (!batchRecords.length) {
+            if (fallbackPromises.length) {
+                await Promise.all(fallbackPromises);
+            }
+            return { success: true, data: { memorized: fallbackRecords.length } };
         }
-        const first = structuredRecords[0];
+        const first = batchRecords[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 rows = [];
+        for (const record of batchRecords) {
             const row = {};
             if (record.email)
                 row.email = record.email;
@@ -940,6 +1003,17 @@ class Personize {
                 row.record_id = record.record_id || record.recordId;
             if (record.customKeyValue)
                 row.custom_key = record.customKeyValue;
+            if (record.content && String(record.content).trim()) {
+                row._content = this.buildContentValueWithMetadata(record);
+                if (!mappingProperties._content) {
+                    mappingProperties._content = {
+                        sourceField: '_content',
+                        collectionId: '',
+                        collectionName: '',
+                        extractMemories: true,
+                    };
+                }
+            }
             for (const [propertyName, rawProperty] of Object.entries(record.properties || {})) {
                 const property = this.isBatchRecordProperty(rawProperty)
                     ? rawProperty
@@ -954,11 +1028,11 @@ class Personize {
                     };
                 }
             }
-            return row;
-        });
-        const unresolvedNames = Array.from(new Set(Object.values(mappingProperties)
-            .filter((property) => !property.collectionId && property.collectionName)
-            .map((property) => property.collectionName)));
+            rows.push(row);
+        }
+        const unresolvedNames = Array.from(new Set(Object.entries(mappingProperties)
+            .filter(([name, property]) => name !== '_content' && !property.collectionId && property.collectionName)
+            .map(([, property]) => property.collectionName)));
         const resolvedMap = new Map();
         if (unresolvedNames.length) {
             const collections = await this.listAllCollections();
@@ -968,7 +1042,9 @@ class Personize {
                 }
             }
         }
-        for (const property of Object.values(mappingProperties)) {
+        for (const [name, property] of Object.entries(mappingProperties)) {
+            if (name === '_content')
+                continue;
             if (!property.collectionId && property.collectionName) {
                 property.collectionId = resolvedMap.get(property.collectionName.toLowerCase()) || '';
             }
@@ -977,7 +1053,7 @@ class Personize {
             }
         }
         const { organizationId, userId } = await this.resolveIdentity();
-        const response = await this.client.post('/api/v1/batch-memorize', {
+        const batchPromise = this.client.post('/api/v1/batch-memorize', {
             source: data.source || 'SDK records shorthand',
             tier: data.tier,
             dryRun: data.dryRun,
@@ -986,6 +1062,7 @@ class Personize {
                 entityType,
                 email: rows.some((row) => row.email) ? 'email' : undefined,
                 website: rows.some((row) => row.website) ? 'website' : undefined,
+                recordId: rows.some((row) => row.record_id) ? 'record_id' : undefined,
                 customKeyName: first.customKeyName,
                 customKey: rows.some((row) => row.custom_key) ? 'custom_key' : undefined,
                 properties: mappingProperties,
@@ -994,7 +1071,11 @@ class Personize {
             orgId: organizationId,
             userId,
         });
-        return response.data;
+        const [batchResponse] = await Promise.all([
+            batchPromise,
+            ...fallbackPromises,
+        ]);
+        return batchResponse.data;
     }
     /**
      * GET /api/v1/test — Verify API key is valid. Returns request metadata and resolved identity.

package/dist/types.d.ts

@@ -851,6 +851,8 @@ export interface BatchMemorizeMapping {
     email?: string;
     /** Source field name that contains the website URL (e.g. 'company_website_url') */
     website?: string;
+    /** Source field name that contains a pre-resolved record ID (e.g. 'record_id') */
+    recordId?: 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.
@@ -981,6 +983,10 @@ export interface SmartDigestOptions {
     deviceId?: string;
     /** Content ID for entity scoping. */
     contentId?: string;
+    /** Custom key name for custom entity types (e.g. 'linkedin_url', 'studentNumber'). */
+    customKeyName?: string;
+    /** Custom key value. Used with customKeyName to scope to a custom-keyed record. */
+    customKeyValue?: string;
 }
 export interface SmartDigestResponse {
     success: boolean;
@@ -1058,6 +1064,27 @@ export interface MemoryItem {
     score?: number;
     metadata?: Record<string, PropertyValue>;
 }
+/** CRM identifier keys for a record, returned in search responses. */
+export interface RecordCrmKeys {
+    type?: string;
+    email?: string;
+    websiteUrl?: string;
+    phoneNumber?: string;
+    postalCode?: string;
+    deviceId?: string;
+    contentId?: string;
+    customKeyName?: string;
+    customKeyValue?: string;
+}
+/** AI extraction metadata aggregated per record, returned in search responses. */
+export interface RecordIndexMeta {
+    entities?: string[];
+    keywords?: string[];
+    persons?: string[];
+    topics?: string[];
+    locations?: string[];
+    sources?: string[];
+}
 export interface SearchResultItem {
     recordId?: string;
     mainProperties?: Record<string, string>;
@@ -1099,6 +1126,10 @@ export interface SearchResponse extends Array<SearchResultItem> {
     memories?: Record<string, MemoryItem[]>;
     /** Compatibility flattened result list derived client-side when possible. */
     results?: SearchResultItem[];
+    /** CRM keys per record (email, phone, website, etc.). */
+    crmKeys?: Record<string, RecordCrmKeys>;
+    /** AI extraction metadata per record (entities, keywords, persons, etc.). */
+    indexMeta?: Record<string, RecordIndexMeta>;
 }
 /** @deprecated Use SearchResponse instead. */
 export type ExportResponse = SearchResponse;
@@ -1727,3 +1758,104 @@ export interface SegmentResponse {
         credits: number;
     };
 }
+/** SmartRecall Unified: 1 endpoint replaces 10 for LLMs/agents. Natural language in, structured intelligence out. */
+export interface SmartRecallUnifiedOptions {
+    /** Natural language query describing what you need from memory. Be specific. */
+    message: string;
+    /** Scope to specific records by identifier. Omit for org-wide queries. */
+    identifiers?: {
+        emails?: string[];
+        websites?: string[];
+        recordIds?: string[];
+        type?: string;
+    };
+    /** Control response depth. Auto-detected from query if omitted. */
+    responseDetail?: 'ids' | 'labels' | 'summary' | 'context' | 'full';
+    /** Max tokens for the response. Default: 4000. */
+    tokenBudget?: number;
+    /** Classification mode. "fast" (~50ms rules), "deep" (~500ms LLM), "auto" (default). */
+    mode?: 'fast' | 'deep' | 'auto';
+    /** Include results from external RAG source (if configured). Default: true. */
+    includeExternalRag?: boolean;
+    /** Include multimodal search results (if enabled). Default: false. */
+    includeMultimodal?: boolean;
+}
+export interface SmartRecallUnifiedRecord {
+    recordId: string;
+    type?: string;
+    email?: string;
+    websiteUrl?: string;
+    label?: string;
+    summary?: Record<string, unknown>;
+    context?: string;
+    memories?: {
+        text: string;
+        topic?: string;
+        score?: number;
+        source?: string;
+    }[];
+    properties?: Record<string, unknown>;
+    score?: number;
+    relevanceTier?: 'direct' | 'partial' | 'might';
+    sources?: string[];
+}
+export interface SmartRecallUnifiedResponse {
+    success: boolean;
+    answer?: string;
+    plan: {
+        classifiedAs: string[];
+        steps: string[];
+        mode: 'fast' | 'deep';
+        confidence: number;
+    };
+    records: SmartRecallUnifiedRecord[];
+    meta: {
+        totalMatched: number;
+        returned: number;
+        enrichmentDepth: string;
+        tokensUsed: number;
+        creditsCharged: number;
+        latencyMs: number;
+        sources: string[];
+    };
+}
+export interface ExternalRAGConfigOptions {
+    url: string;
+    apiKey: string;
+    timeout?: number;
+    maxResults?: number;
+}
+export interface ExternalRAGSearchOptions {
+    query: string;
+    limit?: number;
+    context?: {
+        recordId?: string;
+        type?: string;
+    };
+}
+export interface ExternalRAGSearchResult {
+    text: string;
+    score: number;
+    source: string;
+    url?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface MultimodalMemorizeOptions {
+    recordId: string;
+    type: string;
+    attachment: string;
+    mimeType: string;
+    content?: string;
+}
+export interface MultimodalSearchOptions {
+    image: string;
+    mimeType: string;
+    limit?: number;
+}
+export interface MultimodalSearchResult {
+    recordId: string;
+    score: number;
+    text?: string;
+    sourceUrl?: string;
+    mimeType?: string;
+}

package/package.json

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