@personize/sdk 0.2.0

package/dist/client.js

@@ -0,0 +1,318 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Personize = void 0;
+const axios_1 = __importDefault(require("axios"));
+const errors_1 = require("./errors");
+class Personize {
+    constructor(config) {
+        this.variables = {
+            /**
+             * GET /api/v1/variables — List variables for the organization (paginated).
+             * Pass `limit` and `nextToken` for cursor-based pagination.
+             */
+            list: async (options) => {
+                const params = {};
+                if (options?.limit != null)
+                    params.limit = String(options.limit);
+                if (options?.nextToken)
+                    params.nextToken = options.nextToken;
+                if (options?.summary)
+                    params.summary = 'true';
+                if (options?.tags)
+                    params.tags = Array.isArray(options.tags) ? options.tags.join(',') : options.tags;
+                if (options?.excludeTags)
+                    params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
+                const response = await this.client.get('/api/v1/variables', { params });
+                return response.data;
+            },
+            /**
+             * GET /api/v1/variables/:id/structure — Get variable headings
+             */
+            getStructure: async (id) => {
+                const response = await this.client.get(`/api/v1/variables/${id}/structure`);
+                return response.data;
+            },
+            /**
+             * GET /api/v1/variables/:id/section — Get a section of a variable by header
+             */
+            getSection: async (id, options) => {
+                const response = await this.client.get(`/api/v1/variables/${id}/section`, {
+                    params: { header: options.header },
+                });
+                return response.data;
+            },
+            /**
+             * PATCH /api/v1/variables/:id — Partial update to a variable
+             */
+            update: async (id, payload) => {
+                const organizationId = await this.getOrganizationId();
+                const { historyNote, ...rest } = payload;
+                const response = await this.client.patch(`/api/v1/variables/${id}`, {
+                    organizationId,
+                    historyNote,
+                    payload: rest,
+                });
+                return response.data;
+            },
+            /**
+             * POST /api/v1/variables — Create a new variable
+             */
+            create: async (payload) => {
+                const response = await this.client.post('/api/v1/variables', payload);
+                return response.data;
+            },
+            /**
+             * DELETE /api/v1/variables/:id — Delete a variable
+             */
+            delete: async (id) => {
+                const response = await this.client.delete(`/api/v1/variables/${id}`);
+                return response.data;
+            },
+            /**
+             * GET /api/v1/actions/:id/history — Get version history for a variable
+             */
+            history: async (id, options) => {
+                const organizationId = await this.getOrganizationId();
+                const response = await this.client.get(`/api/v1/actions/${id}/history`, {
+                    params: { organizationId, limit: options?.limit },
+                });
+                return response.data;
+            },
+        };
+        this.collections = {
+            /**
+             * GET /api/v1/collections — List property collections (paginated).
+             * Pass `limit` and `nextToken` for cursor-based pagination.
+             */
+            list: async (options) => {
+                const params = {};
+                if (options?.limit != null)
+                    params.limit = String(options.limit);
+                if (options?.nextToken)
+                    params.nextToken = options.nextToken;
+                if (options?.summary)
+                    params.summary = 'true';
+                if (options?.tags)
+                    params.tags = Array.isArray(options.tags) ? options.tags.join(',') : options.tags;
+                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;
+            },
+            /**
+             * POST /api/v1/collections — Create a new property collection
+             */
+            create: async (payload) => {
+                const response = await this.client.post('/api/v1/collections', payload);
+                return response.data;
+            },
+            /**
+             * PATCH /api/v1/collections/:id — Update a property collection (smart merge for properties array)
+             */
+            update: async (id, payload) => {
+                const organizationId = await this.getOrganizationId();
+                const response = await this.client.patch(`/api/v1/collections/${id}`, {
+                    organizationId,
+                    payload,
+                });
+                return response.data;
+            },
+            /**
+             * DELETE /api/v1/collections/:id — Delete a property collection
+             */
+            delete: async (id) => {
+                const response = await this.client.delete(`/api/v1/collections/${id}`);
+                return response.data;
+            },
+            /**
+             * GET /api/v1/collections/:id/history — Version history for a collection.
+             * Use mode='diff' for token-efficient diffs (~80% fewer tokens than full snapshots).
+             */
+            history: async (id, options) => {
+                const organizationId = await this.getOrganizationId();
+                const response = await this.client.get(`/api/v1/collections/${id}/history`, {
+                    params: { organizationId, limit: options?.limit, mode: options?.mode },
+                });
+                return response.data;
+            },
+        };
+        this.ai = {
+            /**
+             * POST /api/v1/ai/smart-context — Semantic context routing
+             */
+            smartContext: async (options) => {
+                const response = await this.client.post('/api/v1/ai/smart-context', options);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/prompt — Execute a prompt with tools, output extraction, and evaluation.
+             *
+             * Supports simple mode (single prompt) and advanced mode (multi-step instructions).
+             * Use `outputs` for server-side structured output extraction via `<output>` markers.
+             * Use `evaluate` for server-side auto-evaluation.
+             * Use `memorize` to auto-save outputs and tool results to memory.
+             */
+            prompt: async (options) => {
+                const response = await this.client.post('/api/v1/prompt', options);
+                return response.data;
+            },
+        };
+        this.agents = {
+            /**
+             * GET /api/v1/agents — List available agents (paginated).
+             * Pass `limit` and `nextToken` for cursor-based pagination.
+             */
+            list: async (options) => {
+                const params = {};
+                if (options?.limit != null)
+                    params.limit = String(options.limit);
+                if (options?.nextToken)
+                    params.nextToken = options.nextToken;
+                if (options?.summary)
+                    params.summary = 'true';
+                if (options?.tags)
+                    params.tags = Array.isArray(options.tags) ? options.tags.join(',') : options.tags;
+                if (options?.excludeTags)
+                    params.excludeTags = Array.isArray(options.excludeTags) ? options.excludeTags.join(',') : options.excludeTags;
+                const response = await this.client.get('/api/v1/agents', { params });
+                return response.data;
+            },
+            /**
+             * POST /api/v1/agents/:id/run — Run an agent
+             */
+            run: async (id, options) => {
+                const response = await this.client.post(`/api/v1/agents/${id}/run`, options || {});
+                return response.data;
+            },
+        };
+        this.memory = {
+            /**
+             * POST /api/v1/memorize_pro — Advanced memorization (RAG)
+             */
+            memorize: async (data) => {
+                const response = await this.client.post('/api/v1/memorize_pro', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/recall_pro — Advanced recall with reflection (RAG)
+             */
+            recall: async (data) => {
+                const response = await this.client.post('/api/v1/recall_pro', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/export — Filter and export records
+             */
+            export: async (data) => {
+                const response = await this.client.post('/api/v1/export', data);
+                return response.data;
+            },
+            /**
+             * POST /api/v1/upsert — Structured upsert (no AI extraction)
+             */
+            upsert: async (data) => {
+                const organizationId = await this.getOrganizationId();
+                const response = await this.client.post('/api/v1/upsert', {
+                    ...data,
+                    orgId: organizationId,
+                });
+                return response.data;
+            },
+            /**
+             * POST /api/v1/upsert — Batch upsert (memories array format)
+             */
+            upsertBatch: async (data) => {
+                const organizationId = await this.getOrganizationId();
+                const response = await this.client.post('/api/v1/upsert', {
+                    ...data,
+                    orgId: organizationId,
+                });
+                return response.data;
+            },
+            /**
+             * POST /api/v1/batch-memorize — Unified batch sync with per-property extractMemories flag.
+             * Properties with extractMemories: true go through AI extraction + vectors.
+             * Properties without it (or false) are stored as structured data only.
+             */
+            memorizeBatch: async (data) => {
+                const { organizationId, userId } = await this.resolveIdentity();
+                const response = await this.client.post('/api/v1/batch-memorize', {
+                    ...data,
+                    orgId: organizationId,
+                    userId,
+                });
+                return response.data;
+            },
+            /**
+             * POST /api/v1/smart-memory-digest — Get compiled context bundle for an entity.
+             * Combines DynamoDB properties + LanceDB memories into a token-budgeted markdown block.
+             */
+            smartDigest: async (data) => {
+                const response = await this.client.post('/api/v1/smart-memory-digest', data);
+                return response.data;
+            },
+        };
+        this.maxRetries = config.maxRetries ?? 3;
+        this.retryDelay = config.retryDelay ?? 1000;
+        this.client = axios_1.default.create({
+            baseURL: config.baseURL || 'https://api.personize.ai',
+            timeout: config.timeout ?? 30000,
+            headers: {
+                'Authorization': `Bearer ${config.secretKey}`,
+                'Content-Type': 'application/json',
+            },
+        });
+        this.client.interceptors.response.use((response) => response, async (error) => {
+            const reqConfig = error.config;
+            if (!reqConfig)
+                throw (0, errors_1.toPersonizeError)(error);
+            const retryCount = reqConfig._retryCount ?? 0;
+            const status = error.response?.status;
+            const isRetryable = status === 429 || (status !== undefined && status >= 500);
+            if (isRetryable && retryCount < this.maxRetries) {
+                reqConfig._retryCount = retryCount + 1;
+                let delay;
+                if (status === 429) {
+                    const body = error.response?.data;
+                    const retryAfter = body?.retryAfterSeconds || 0;
+                    delay = retryAfter > 0
+                        ? retryAfter * 1000
+                        : this.retryDelay * Math.pow(2, retryCount);
+                }
+                else {
+                    delay = this.retryDelay * Math.pow(2, retryCount);
+                }
+                await new Promise(resolve => setTimeout(resolve, delay));
+                return this.client.request(reqConfig);
+            }
+            throw (0, errors_1.toPersonizeError)(error);
+        });
+    }
+    async resolveIdentity() {
+        if (!this._organizationId || !this._userId) {
+            const me = await this.me();
+            this._organizationId = me.data?.organization?.id;
+            this._userId = me.data?.user?.id;
+        }
+        if (!this._organizationId)
+            throw new Error('Could not resolve organizationId from API key');
+        if (!this._userId)
+            throw new Error('Could not resolve userId from API key');
+        return { organizationId: this._organizationId, userId: this._userId };
+    }
+    async getOrganizationId() {
+        const { organizationId } = await this.resolveIdentity();
+        return organizationId;
+    }
+    /**
+     * GET /api/v1/me — Current context (org, user, plan)
+     */
+    async me() {
+        const response = await this.client.get('/api/v1/me');
+        return response.data;
+    }
+}
+exports.Personize = Personize;

package/dist/errors.d.ts

@@ -0,0 +1,58 @@
+import { AxiosError } from 'axios';
+/**
+ * Base error class for all Personize SDK errors.
+ */
+export declare class PersonizeError extends Error {
+    readonly status?: number;
+    readonly endpoint?: string;
+    readonly method?: string;
+    readonly cause?: AxiosError;
+    constructor(message: string, options?: {
+        status?: number;
+        endpoint?: string;
+        method?: string;
+        cause?: AxiosError;
+    });
+}
+/**
+ * Thrown when the API returns 401 (invalid/expired API key).
+ */
+export declare class AuthenticationError extends PersonizeError {
+    constructor(message: string, options?: {
+        endpoint?: string;
+        method?: string;
+        cause?: AxiosError;
+    });
+}
+/**
+ * Thrown when the API returns 429 (rate limit exceeded).
+ */
+export declare class RateLimitExceededError extends PersonizeError {
+    readonly limit?: number;
+    readonly current?: number;
+    readonly window?: 'per_minute' | 'per_month';
+    readonly retryAfterSeconds?: number;
+    constructor(message: string, options?: {
+        endpoint?: string;
+        method?: string;
+        cause?: AxiosError;
+        limit?: number;
+        current?: number;
+        window?: 'per_minute' | 'per_month';
+        retryAfterSeconds?: number;
+    });
+}
+/**
+ * Thrown when a request times out.
+ */
+export declare class TimeoutError extends PersonizeError {
+    constructor(message: string, options?: {
+        endpoint?: string;
+        method?: string;
+        cause?: AxiosError;
+    });
+}
+/**
+ * Converts an AxiosError into the appropriate PersonizeError subclass.
+ */
+export declare function toPersonizeError(error: AxiosError): PersonizeError;

package/dist/errors.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TimeoutError = exports.RateLimitExceededError = exports.AuthenticationError = exports.PersonizeError = void 0;
+exports.toPersonizeError = toPersonizeError;
+/**
+ * Base error class for all Personize SDK errors.
+ */
+class PersonizeError extends Error {
+    constructor(message, options) {
+        super(message);
+        this.name = 'PersonizeError';
+        this.status = options?.status;
+        this.endpoint = options?.endpoint;
+        this.method = options?.method;
+        this.cause = options?.cause;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+exports.PersonizeError = PersonizeError;
+/**
+ * Thrown when the API returns 401 (invalid/expired API key).
+ */
+class AuthenticationError extends PersonizeError {
+    constructor(message, options) {
+        super(message, { ...options, status: 401 });
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+/**
+ * Thrown when the API returns 429 (rate limit exceeded).
+ */
+class RateLimitExceededError extends PersonizeError {
+    constructor(message, options) {
+        super(message, { ...options, status: 429 });
+        this.name = 'RateLimitExceededError';
+        this.limit = options?.limit;
+        this.current = options?.current;
+        this.window = options?.window;
+        this.retryAfterSeconds = options?.retryAfterSeconds;
+    }
+}
+exports.RateLimitExceededError = RateLimitExceededError;
+/**
+ * Thrown when a request times out.
+ */
+class TimeoutError extends PersonizeError {
+    constructor(message, options) {
+        super(message, { ...options, status: undefined });
+        this.name = 'TimeoutError';
+    }
+}
+exports.TimeoutError = TimeoutError;
+/**
+ * Converts an AxiosError into the appropriate PersonizeError subclass.
+ */
+function toPersonizeError(error) {
+    const endpoint = error.config?.url;
+    const method = error.config?.method?.toUpperCase();
+    const status = error.response?.status;
+    const body = error.response?.data;
+    if (error.code === 'ECONNABORTED' || error.code === 'ETIMEDOUT') {
+        return new TimeoutError(`Request timed out: ${method} ${endpoint}`, { endpoint, method, cause: error });
+    }
+    if (status === 401) {
+        return new AuthenticationError(body?.message || 'Invalid or expired API key', { endpoint, method, cause: error });
+    }
+    if (status === 429) {
+        return new RateLimitExceededError(body?.message || 'Rate limit exceeded', {
+            endpoint,
+            method,
+            cause: error,
+            limit: body?.limit,
+            current: body?.current,
+            window: body?.window,
+            retryAfterSeconds: body?.retryAfterSeconds,
+        });
+    }
+    if (!error.response) {
+        return new PersonizeError(`Network error: ${error.message}`, { endpoint, method, cause: error });
+    }
+    const message = body?.message
+        || body?.error
+        || `Request failed with status ${status}`;
+    return new PersonizeError(`${message} (${method} ${endpoint})`, { status, endpoint, method, cause: error });
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from './types';
+export * from './client';
+export * from './errors';

package/dist/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./client"), exports);
+__exportStar(require("./errors"), exports);