@personize/sdk 0.6.1 → 0.6.2

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,23 @@ 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
+
 // 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 +292,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 +307,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 +398,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 +428,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 +453,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
 

package/dist/types.d.ts

@@ -551,6 +551,16 @@ 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;
     /** Tags for property selection. */
@@ -587,6 +597,10 @@ 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). */
@@ -635,6 +649,10 @@ 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>;
 }
@@ -649,12 +667,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 */

package/package.json

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