@personize/sdk 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,567 @@
+export type PropertyValue = string | number | boolean | null;
+export interface PersonizeConfig {
+    secretKey: string;
+    baseURL?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Maximum number of retry attempts for 429 and 5xx errors (default: 3) */
+    maxRetries?: number;
+    /** Base delay in milliseconds for exponential backoff (default: 1000) */
+    retryDelay?: number;
+}
+export interface ApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+    message?: string;
+}
+export interface RateLimitError {
+    success: false;
+    error: 'rate_limit_exceeded';
+    message: string;
+    limit: number;
+    current: number;
+    window: 'per_minute' | 'per_month';
+    retryAfterSeconds?: number;
+}
+export interface MeResponse {
+    organization: {
+        id: string;
+    };
+    user: {
+        id: string;
+    };
+    key: {
+        id: string;
+        scope: string;
+    };
+    plan: {
+        id: string;
+        name: string;
+        description: string;
+        limits: {
+            maxApiCallsPerMonth: number;
+            maxApiCallsPerMinute: number;
+        };
+        features: string[];
+    };
+}
+export interface ListOptions {
+    /** Page size (default: 25, max: 100). */
+    limit?: number;
+    /** Cursor returned by the previous page. Pass to fetch the next page. */
+    nextToken?: string;
+    /** Filter by tags (comma-separated or array). */
+    tags?: string | string[];
+    /** Exclude items with these tags. */
+    excludeTags?: string | string[];
+    /** When true, strip the full `value` field for lighter payloads. */
+    summary?: boolean;
+}
+export interface VariablesResponse {
+    actions: Array<{
+        id: string;
+        type: string;
+        payload: {
+            name: string;
+            value: string;
+            [key: string]: PropertyValue;
+        };
+    }>;
+    count: number;
+    /** Cursor for the next page. Undefined when on the last page. */
+    nextToken?: string;
+}
+export interface VariableSectionOptions {
+    header: string;
+}
+export interface VariableUpdatePayload {
+    name?: string;
+    value?: string;
+    description?: string;
+    tags?: string[];
+    secure?: boolean;
+    updateMode?: 'replace' | 'append' | 'section' | 'appendToSection';
+    sectionHeader?: string;
+    separator?: string;
+    historyNote?: string;
+}
+export interface VariableCreatePayload {
+    name: string;
+    value?: string;
+    description?: string;
+    tags?: string[];
+    secure?: boolean;
+}
+export interface VariableHistoryEntry {
+    id: string;
+    originalActionId: string;
+    type: string;
+    timestamp: string;
+    changeType?: 'update' | 'restore' | 'delete';
+    modifiedBy?: string;
+    modifiedByEmail?: string;
+    note?: string;
+    versionSource?: 'manual' | 'auto-save' | 'restore';
+    payload: {
+        name: string;
+        value: string;
+        [key: string]: PropertyValue;
+    };
+}
+export interface VariableHistoryResponse {
+    actionId: string;
+    history: VariableHistoryEntry[];
+    count: number;
+}
+export interface VariableHistoryOptions {
+    /** Max number of history records to return (default: 20, max: 50).
+     * Each entry includes the full variable content snapshot, so use a small limit (3-5) in token-sensitive contexts. */
+    limit?: number;
+}
+export interface CollectionsResponse {
+    actions: Array<{
+        id: string;
+        type: string;
+        payload: {
+            collectionName: string;
+            collectionId: string;
+            [key: string]: PropertyValue;
+        };
+    }>;
+    count: number;
+    /** Cursor for the next page. Undefined when on the last page. */
+    nextToken?: string;
+}
+export interface CollectionCreatePayload {
+    collectionName: string;
+    collectionId?: string;
+    definition?: string;
+    entityType?: string;
+    properties?: Array<{
+        propertyName: string;
+        propertyId?: string;
+        systemName?: string;
+        type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
+        options?: string;
+        description?: string;
+        autoSystem?: boolean;
+        update?: boolean;
+        status?: 'Active' | 'Deleted';
+    }>;
+    status?: 'Active' | 'Deleted';
+}
+export interface CollectionUpdatePayload {
+    collectionName?: string;
+    definition?: string;
+    entityType?: string;
+    properties?: Array<{
+        propertyId?: string;
+        propertyName?: string;
+        systemName?: string;
+        type?: 'text' | 'date' | 'options' | 'number' | 'boolean' | 'array';
+        options?: string;
+        description?: string;
+        autoSystem?: boolean;
+        update?: boolean;
+        status?: 'Active' | 'Deleted';
+    }>;
+    status?: 'Active' | 'Deleted';
+}
+export interface CollectionHistoryOptions {
+    /** Max number of history records to return (default: 20, max: 50). */
+    limit?: number;
+    /** 'full' returns raw snapshots; 'diff' returns latest snapshot + compact per-version diffs (~80% fewer tokens). Default: 'full'. */
+    mode?: 'full' | 'diff';
+}
+export interface CollectionPropertyDiff {
+    propertiesAdded: Array<{
+        propertyId: string;
+        systemName: string;
+        propertyName: string;
+    }>;
+    propertiesRemoved: Array<{
+        propertyId: string;
+        systemName: string;
+        propertyName: string;
+    }>;
+    propertiesModified: Array<{
+        propertyId: string;
+        systemName: string;
+        fields: Record<string, {
+            from: unknown;
+            to: unknown;
+        }>;
+    }>;
+    metadataChanges: Record<string, {
+        from: unknown;
+        to: unknown;
+    }>;
+}
+export interface CollectionHistoryResponse {
+    actionId: string;
+    mode: 'full' | 'diff';
+    /** mode=full: raw history snapshots */
+    history?: Array<Record<string, unknown>>;
+    count?: number;
+    /** mode=diff: latest full snapshot */
+    current?: Record<string, unknown> | null;
+    /** mode=diff: compact per-version diffs (newest first) */
+    versions?: Array<{
+        timestamp: string;
+        historyNote?: string;
+        changes: CollectionPropertyDiff;
+    }>;
+}
+export interface SmartContextOptions {
+    message: string;
+    variableIds?: string[];
+    tags?: string[];
+    excludeTags?: string[];
+    model?: string;
+    /** Routing mode: "fast" for instant embedding-only (~200ms), "full" for deep LLM routing (~3s), "auto" to let the system decide. Default: "auto". */
+    mode?: 'fast' | 'full' | 'auto';
+    /** Minimum cosine similarity score (0-1) for fast mode results. Lower values return more results. Default: 0.4 for supplementary, 0.7 for critical. */
+    minScore?: number;
+}
+export interface SmartContextAnalysis {
+    taskUnderstanding: string;
+    qualityDimensions: string[];
+    refinedTask: string;
+}
+export interface SmartContextSelection {
+    variableId: string;
+    name?: string;
+    score?: number;
+    reason?: string;
+    priority?: string;
+    content?: string;
+    contentLength?: number;
+    mode?: string;
+    sections?: string[];
+}
+export interface SmartContextUsage {
+    durationMs: number;
+    tokensUsed?: number;
+    variablesScanned?: number;
+    selectedCount?: number;
+    preFilter?: {
+        total: number;
+        passed: number;
+        noEmbedding: number;
+        durationMs: number;
+    };
+}
+export interface SmartContextResponse {
+    success: boolean;
+    /** Which routing mode was actually used. */
+    mode: 'fast' | 'full';
+    /** LLM analysis of the task. Null in fast mode. */
+    analysis?: SmartContextAnalysis | null;
+    selection: SmartContextSelection[];
+    supplementary?: SmartContextSelection[];
+    compiledContext: string;
+    usage: SmartContextUsage;
+}
+/**
+ * Per-MCP tool selection override.
+ * Use enabledTools for an explicit allowlist, or disabledTools for a denylist.
+ */
+export interface McpToolSelection {
+    mcpId: string;
+    enabledTools?: string[];
+    disabledTools?: string[];
+}
+/** Auto-memorize configuration for /prompt. */
+export interface PromptMemorizeConfig {
+    /** Contact email identifier. */
+    email?: string;
+    /** Company website identifier. */
+    websiteUrl?: string;
+    /** Generic record identifier. */
+    recordId?: string;
+    /** Entity type. */
+    type?: 'Contact' | 'Company' | 'User';
+    /**
+     * When true, tool results from research tools (search_companies, tavily, etc.)
+     * are automatically captured and memorized. Meta tools (smart_context,
+     * recall_pro, memorize_pro, store_evaluation_log) are excluded.
+     */
+    captureToolResults?: boolean;
+}
+/** Server-side evaluation configuration. */
+export type PromptEvaluateConfig = boolean | {
+    /** Evaluation criteria: preset name ('sales', 'research', etc.) or custom string. */
+    criteria?: string;
+    /** When true, server evaluates using gpt-4o-mini instead of relying on LLM tool call. */
+    serverSide?: boolean;
+};
+/** Named output to extract from LLM response via <output> XML markers. */
+export interface PromptOutputDefinition {
+    /** Unique name for this output (used in <output name="..."> markers). */
+    name: string;
+}
+export interface PromptOptions {
+    prompt?: string;
+    instructions?: Array<string | {
+        prompt: string;
+        maxSteps?: number;
+    }>;
+    stream?: boolean;
+    model?: string;
+    provider?: string;
+    context?: string;
+    sessionId?: string;
+    /**
+     * Evaluation configuration.
+     * - `true` — server-side auto-evaluation with default criteria
+     * - `{ criteria: 'sales', serverSide: true }` — server-side with preset/custom criteria
+     */
+    evaluate?: PromptEvaluateConfig;
+    /**
+     * Auto-memorize extracted outputs and/or captured tool results.
+     * Requires at least one identifier (email, websiteUrl, or recordId).
+     */
+    memorize?: PromptMemorizeConfig;
+    /**
+     * Named outputs to extract from LLM response via `<output name="...">` XML markers.
+     * Server-side extraction replaces unreliable LLM tool calls for structured output.
+     */
+    outputs?: PromptOutputDefinition[];
+    metadata?: {
+        recordId?: string;
+    };
+    /** Per-MCP tool selection override (allowlist or denylist per MCP) */
+    mcpTools?: McpToolSelection[];
+}
+/** Prompt response when outputs/evaluation are used. */
+export interface PromptResponse {
+    success: boolean;
+    text: string;
+    /** Extracted structured outputs (from <output> markers). */
+    outputs?: Record<string, unknown>;
+    /** Server-side evaluation result. */
+    evaluation?: {
+        finalScore: number;
+        criteriaScores: Array<{
+            name: string;
+            score: number;
+            maxScore: number;
+            reason: string;
+        }>;
+        explanation: string;
+    };
+    metadata?: {
+        model: string;
+        provider: string;
+        usage?: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+        toolCalls?: Array<{
+            toolName: string;
+        }>;
+        stepsExecuted?: number;
+        instructionsExecuted?: number;
+    };
+    steps?: Array<{
+        instructionIndex: number;
+        text: string;
+        usage?: {
+            promptTokens: number;
+            completionTokens: number;
+            totalTokens: number;
+        };
+        toolCalls?: Array<{
+            toolName: string;
+        }>;
+        stepsExecuted: number;
+    }>;
+}
+export interface AgentRunOptions {
+    inputs?: Record<string, unknown>;
+    stream?: boolean;
+    email?: string;
+    websiteUrl?: string;
+    recordId?: string;
+    /** Per-MCP tool selection override (allowlist or denylist per MCP) */
+    mcpTools?: McpToolSelection[];
+}
+export interface MemorizeProOptions {
+    content: string;
+    speaker?: string;
+    timestamp?: string;
+    schema?: Record<string, unknown>;
+    actionId?: string;
+    record_id?: string;
+    email?: string;
+    website_url?: string;
+    enhanced?: boolean;
+    tags?: string[];
+    max_properties?: number;
+}
+export interface RecallProOptions {
+    query: string;
+    limit?: number;
+    minScore?: number;
+    record_id?: string;
+    email?: string;
+    website_url?: string;
+    type?: string;
+    include_property_values?: boolean;
+    enable_reflection?: boolean;
+    generate_answer?: boolean;
+    /**
+     * Fast mode: skip reflection loop and answer generation, use minScore 0.3,
+     * return all results above the score threshold (no hard limit).
+     * Reduces latency from ~10-20s to ~500-700ms.
+     */
+    fast_mode?: boolean;
+    /**
+     * Minimum relevance score (0-1). Filters out results below this threshold.
+     * In fast_mode, defaults to 0.3 if not specified.
+     */
+    min_score?: number;
+}
+export interface UpsertOptions {
+    /** Entity type (e.g. 'Contact', 'Company') */
+    type: string;
+    /** Properties to store: { propertyName: { value, collectionId?, collectionName? } } */
+    properties: Record<string, {
+        value: PropertyValue;
+        collectionId?: string;
+        collectionName?: string;
+    }>;
+    /** Match keys for dedup (e.g. { email: 'john@example.com' }) */
+    matchKeys?: {
+        email?: string;
+        websiteUrl?: string;
+    };
+    /** Source label (e.g. 'CRM Sync') */
+    source?: string;
+}
+export interface UpsertBatchOptions {
+    /** Entity type */
+    type: string;
+    /** Array of memory items to upsert */
+    memories: Array<{
+        memoryName: string;
+        result: PropertyValue | Record<string, unknown>;
+        collection?: string;
+        collectionId?: string;
+    }>;
+    /** Contact email for record matching */
+    email?: string;
+    /** Company website for record matching */
+    websiteUrl?: string;
+    /** Source label */
+    source?: string;
+}
+export interface BatchMemorizePropertyMapping {
+    /** Source field name in the row data */
+    sourceField: string;
+    /** Target collection ID */
+    collectionId: string;
+    /** Target collection name */
+    collectionName: string;
+    /** If true, AI extraction + vector embeddings are created for this property. Default: false (structured storage only). */
+    extractMemories?: boolean;
+}
+export interface BatchMemorizeMapping {
+    /** Entity type (e.g. 'contact', 'company') */
+    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;
+    /** Run name for tracking (e.g. 'hubspot Sync (contact) - <uuid>') */
+    runName?: string;
+    /** Property mappings: target property name → mapping config */
+    properties: Record<string, BatchMemorizePropertyMapping>;
+}
+export interface BatchMemorizeOptions {
+    /** Source system label (e.g. 'Hubspot', 'Salesforce') */
+    source: string;
+    /** Mapping configuration for the sync */
+    mapping: BatchMemorizeMapping;
+    /** Array of source data rows (key-value objects matching sourceField names) */
+    rows: Record<string, unknown>[];
+    /** If true, validate without writing (default: false) */
+    dryRun?: boolean;
+    /** Number of rows to process per chunk (default: 1) */
+    chunkSize?: number;
+}
+export interface SmartDigestOptions {
+    /** CRM record ID */
+    record_id?: string;
+    /** Contact email */
+    email?: string;
+    /** Company website URL */
+    website_url?: string;
+    /** Entity type ('Contact', 'Company'). Auto-inferred if omitted. */
+    type?: string;
+    /** Max tokens for compiled context (default: 1000) */
+    token_budget?: number;
+    /** Max free-form memories to include (default: 20) */
+    max_memories?: number;
+    /** Include DynamoDB property snapshot (default: true) */
+    include_properties?: boolean;
+    /** Include LanceDB free-form memories (default: true) */
+    include_memories?: boolean;
+}
+export interface SmartDigestResponse {
+    success: boolean;
+    recordId?: string;
+    type?: string;
+    properties: Record<string, string>;
+    memories: Array<{
+        text: string;
+        createdAt?: string;
+    }>;
+    /** Ready-to-use markdown string for prompt injection */
+    compiledContext: string;
+    tokenEstimate: number;
+    tokenBudget: number;
+}
+export interface ExportOptions {
+    groups?: Array<{
+        id: string;
+        logic: 'AND' | 'OR';
+        conditions: Array<{
+            field: string;
+            operator: string;
+            value?: PropertyValue;
+            collectionId?: string;
+        }>;
+    }>;
+    type?: string;
+    email?: string;
+    websiteUrl?: string;
+    recordId?: string;
+    collectionIds?: string[];
+    page?: number;
+    pageSize?: number;
+    countOnly?: boolean;
+    returnRecords?: boolean;
+    includeMemories?: boolean;
+}
+export interface MemoryItem {
+    text: string;
+    createdAt?: string;
+    score?: number;
+    metadata?: Record<string, PropertyValue>;
+}
+export interface ExportResponse {
+    recordIds: string[];
+    totalMatched: number;
+    page: number;
+    pageSize: number;
+    totalPages: number;
+    records?: Record<string, Record<string, {
+        value: PropertyValue;
+        collectionId: string;
+        collectionName?: string;
+    }>>;
+    memories?: Record<string, MemoryItem[]>;
+}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+// --- Utility Types ---
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "@personize/sdk",
+    "version": "0.2.0",
+    "description": "Official Personize SDK",
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "files": [
+        "dist/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "build": "tsc",
+        "prepublishOnly": "npm run build",
+        "test": "jest",
+        "test:watch": "jest --watch",
+        "test:coverage": "jest --coverage"
+    },
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/hataheri/personize-sdk.git"
+    },
+    "homepage": "https://personize.ai",
+    "bugs": {
+        "url": "https://github.com/hataheri/personize-sdk/issues"
+    },
+    "keywords": [
+        "personize",
+        "ai",
+        "sdk",
+        "memory",
+        "agents"
+    ],
+    "author": "Personize",
+    "license": "Apache-2.0",
+    "devDependencies": {
+        "typescript": "^5.0.0",
+        "@types/node": "^18.0.0",
+        "@types/jest": "^29.5.0",
+        "jest": "^29.7.0",
+        "ts-jest": "^29.1.0",
+        "nock": "^14.0.0"
+    },
+    "dependencies": {
+        "axios": "^1.6.0"
+    }
+}