@scitrera/memorylayer-sdk 0.0.5 → 0.1.22

package/dist/client.js

@@ -1,16 +1,34 @@
-import { MemoryLayerError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError } from "./errors.js";
+import { MemoryLayerError, AuthenticationError, AuthorizationError, NotFoundError, ValidationError, EnterpriseRequiredError } from "./errors.js";
+import { SkillsNamespace } from "./skills.js";
+import { McpServersNamespace } from "./mcp_servers.js";
 export class MemoryLayerClient {
     baseUrl;
     apiKey;
     workspaceId;
     sessionId;
     timeout;
+    defaultAuthority;
+    /** Skills namespace — access via `client.skills.list(...)` etc. */
+    skills;
+    /** MCP Servers namespace — access via `client.mcpServers.list(...)` etc. */
+    mcpServers;
     constructor(config = {}) {
         this.baseUrl = config.baseUrl ?? "http://localhost:61001";
         this.apiKey = config.apiKey;
         this.workspaceId = config.workspaceId;
         this.sessionId = config.sessionId;
         this.timeout = config.timeout ?? 30000;
+        this.defaultAuthority = config.defaultAuthority;
+        this.skills = new SkillsNamespace(this);
+        this.mcpServers = new McpServersNamespace(this);
+    }
+    /**
+     * Returns a lightweight proxy that sends OBO headers for the given grant/subject
+     * on every request. The proxy is synchronous and reuses the parent client's
+     * connection settings — safe for concurrent use across multiple subjects.
+     */
+    actingFor(opts) {
+        return new OboProxy(this, { grantId: opts.grantId, subject: opts.subject });
     }
     /**
      * Set the active session ID. All subsequent requests will include
@@ -32,7 +50,19 @@ export class MemoryLayerClient {
     getSessionId() {
         return this.sessionId;
     }
-    async request(method, path, body) {
+    buildAuthorityHeaders(authority) {
+        const resolved = authority ?? this.defaultAuthority;
+        if (!resolved)
+            return {};
+        const h = {
+            "X-Aether-Grant-ID": resolved.grantId,
+            "X-Aether-Authority-Mode": "on_behalf_of",
+            "X-Aether-Subject-Type": resolved.subject.type,
+            "X-Aether-Subject-ID": resolved.subject.id,
+        };
+        return h;
+    }
+    async request(method, path, body, enterpriseFeature, authority) {
         const headers = {
             "Content-Type": "application/json",
         };
@@ -45,6 +75,7 @@ export class MemoryLayerClient {
         if (this.workspaceId) {
             headers["X-Workspace-ID"] = this.workspaceId;
         }
+        Object.assign(headers, this.buildAuthorityHeaders(authority));
         const url = `${this.baseUrl}${path}`;
         const controller = new AbortController();
         const timeoutId = setTimeout(() => controller.abort(), this.timeout);
@@ -57,7 +88,7 @@ export class MemoryLayerClient {
             });
             clearTimeout(timeoutId);
             if (!response.ok) {
-                await this.handleError(response);
+                await this.handleError(response, enterpriseFeature);
             }
             if (response.status === 204) {
                 return undefined;
@@ -70,7 +101,7 @@ export class MemoryLayerClient {
             throw new MemoryLayerError(`Request failed: ${error}`);
         }
     }
-    async handleError(response) {
+    async handleError(response, enterpriseFeature) {
         const body = await response.json().catch(() => ({}));
         const rawDetail = body.message ?? body.detail ?? response.statusText;
         const message = typeof rawDetail === 'string'
@@ -86,6 +117,11 @@ export class MemoryLayerClient {
             case 400:
             case 422:
                 throw new ValidationError(message, body.details);
+            case 501:
+                if (enterpriseFeature) {
+                    throw new EnterpriseRequiredError(enterpriseFeature);
+                }
+                throw new NotFoundError(message);
             default:
                 throw new MemoryLayerError(message, response.status);
         }
@@ -103,8 +139,9 @@ export class MemoryLayerClient {
             metadata: options.metadata ?? {},
             associations: options.associations ?? [],
             context_id: options.contextId,
+            user_id: options.userId,
         };
-        const response = await this.request("POST", "/v1/memories", body);
+        const response = await this.request("POST", "/v1/memories", body, undefined, options.authority);
         return response.memory;
     }
     async recall(query, options = {}) {
@@ -130,8 +167,9 @@ export class MemoryLayerClient {
             context: options.conversationContext ?? [],
             rag_threshold: options.ragThreshold,
             detail_level: options.detailLevel,
+            user_id: options.userId,
         };
-        return this.request("POST", "/v1/memories/recall", body);
+        return this.request("POST", "/v1/memories/recall", body, undefined, options.authority);
     }
     async reflect(query, options = {}) {
         const body = {
@@ -145,8 +183,9 @@ export class MemoryLayerClient {
             subtypes: options.subtypes ?? [],
             tags: options.tags ?? [],
             context_id: options.contextId,
+            user_id: options.userId,
         };
-        return this.request("POST", "/v1/memories/reflect", body);
+        return this.request("POST", "/v1/memories/reflect", body, undefined, options.authority);
     }
     async getMemory(memoryId) {
         const response = await this.request("GET", `/v1/memories/${memoryId}`);
@@ -577,5 +616,456 @@ export class MemoryLayerClient {
     async contextCheckpoint() {
         await this.request("POST", "/v1/context/checkpoint");
     }
+    // ------------------------------------------------------------------ //
+    // Document operations (Enterprise)
+    // ------------------------------------------------------------------ //
+    /**
+     * Upload a document for ingestion.
+     *
+     * Requires MemoryLayer Enterprise. On OSS servers this throws
+     * `EnterpriseRequiredError`.
+     */
+    async uploadDocument(file, filename, options = {}) {
+        const formData = new FormData();
+        formData.append("file", file, filename);
+        if (options.targetContextId)
+            formData.append("target_context_id", options.targetContextId);
+        if (options.chunkingStrategy)
+            formData.append("chunking_strategy", options.chunkingStrategy);
+        if (options.chunkSize !== undefined)
+            formData.append("chunk_size", String(options.chunkSize));
+        if (options.chunkOverlap !== undefined)
+            formData.append("chunk_overlap", String(options.chunkOverlap));
+        if (options.importance !== undefined)
+            formData.append("importance", String(options.importance));
+        if (options.retainOriginal !== undefined)
+            formData.append("retain_original", String(options.retainOriginal));
+        const headers = {};
+        if (this.apiKey)
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        if (this.sessionId)
+            headers["X-Session-ID"] = this.sessionId;
+        if (this.workspaceId)
+            headers["X-Workspace-ID"] = this.workspaceId;
+        const url = `${this.baseUrl}/v1/documents`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers,
+                body: formData,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                await this.handleError(response, "Document ingestion");
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof MemoryLayerError)
+                throw error;
+            throw new MemoryLayerError(`Document upload failed: ${error}`);
+        }
+    }
+    /**
+     * List documents in the workspace.
+     */
+    async listDocuments(options) {
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set("status", options.status);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options?.offset !== undefined)
+            params.set("offset", String(options.offset));
+        const query = params.toString();
+        return this.request("GET", `/v1/documents${query ? `?${query}` : ""}`, undefined, "Document management");
+    }
+    /**
+     * Get document metadata and processing status.
+     */
+    async getDocument(documentId) {
+        const response = await this.request("GET", `/v1/documents/${documentId}`, undefined, "Document management");
+        return response;
+    }
+    /**
+     * Delete a document and optionally its extracted memories.
+     */
+    async deleteDocument(documentId, deleteMemories = false) {
+        await this.request("DELETE", `/v1/documents/${documentId}?delete_memories=${deleteMemories}`, undefined, "Document management");
+    }
+    /**
+     * Search document pages using ColPali MaxSim visual similarity.
+     *
+     * Requires MemoryLayer Enterprise.
+     */
+    async searchDocumentPages(query, options = {}) {
+        const body = {
+            query,
+            limit: options.limit ?? 10,
+            doc_ids: options.docIds,
+        };
+        return this.request("POST", "/v1/documents/search", body, "Document page search");
+    }
+    /**
+     * Get all pages for a document.
+     */
+    async getDocumentPages(documentId) {
+        return this.request("GET", `/v1/documents/${documentId}/pages`, undefined, "Document pages");
+    }
+    /**
+     * Get a page image as a Blob.
+     */
+    async getPageImage(documentId, pageId) {
+        const headers = {};
+        if (this.apiKey)
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        if (this.sessionId)
+            headers["X-Session-ID"] = this.sessionId;
+        if (this.workspaceId)
+            headers["X-Workspace-ID"] = this.workspaceId;
+        const url = `${this.baseUrl}/v1/documents/${documentId}/pages/${pageId}/image`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, { method: "GET", headers, signal: controller.signal });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                await this.handleError(response, "Document page images");
+            }
+            return await response.blob();
+        }
+        catch (error) {
+            if (error instanceof MemoryLayerError)
+                throw error;
+            throw new MemoryLayerError(`Page image request failed: ${error}`);
+        }
+    }
+    /**
+     * Get ingestion job status.
+     */
+    async getJob(jobId) {
+        return this.request("GET", `/v1/documents/jobs/${jobId}`, undefined, "Document ingestion jobs");
+    }
+    /**
+     * List ingestion jobs in the workspace.
+     */
+    async listJobs(options) {
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set("status", options.status);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        const query = params.toString();
+        return this.request("GET", `/v1/documents/jobs${query ? `?${query}` : ""}`, undefined, "Document ingestion jobs");
+    }
+    /**
+     * Cancel a running ingestion job.
+     */
+    async cancelJob(jobId) {
+        await this.request("POST", `/v1/documents/jobs/${jobId}/cancel`, undefined, "Document ingestion jobs");
+    }
+    /**
+     * Reprocess a document with optionally different extraction options.
+     */
+    async reprocessDocument(documentId, options) {
+        const body = {};
+        if (options?.targetContextId)
+            body.target_context_id = options.targetContextId;
+        if (options?.chunkingStrategy)
+            body.chunking_strategy = options.chunkingStrategy;
+        if (options?.chunkSize !== undefined)
+            body.chunk_size = options.chunkSize;
+        if (options?.chunkOverlap !== undefined)
+            body.chunk_overlap = options.chunkOverlap;
+        if (options?.importance !== undefined)
+            body.importance = options.importance;
+        return this.request("POST", `/v1/documents/${documentId}/reprocess`, Object.keys(body).length ? body : undefined, "Document reprocessing");
+    }
+    // ------------------------------------------------------------------ //
+    // Chat History operations
+    // ------------------------------------------------------------------ //
+    async createThread(options = {}) {
+        const body = {
+            thread_id: options.threadId,
+            workspace_id: options.workspaceId ?? this.workspaceId,
+            user_id: options.userId,
+            context_id: options.contextId,
+            observer_id: options.observerId,
+            subject_id: options.subjectId,
+            title: options.title,
+            metadata: options.metadata,
+            expires_at: options.expiresAt,
+        };
+        const response = await this.request("POST", "/v1/threads", body);
+        return response.thread;
+    }
+    async listThreads(options = {}) {
+        const params = new URLSearchParams();
+        const wsId = options.workspaceId ?? this.workspaceId;
+        if (wsId)
+            params.set("workspace_id", wsId);
+        if (options.userId)
+            params.set("user_id", options.userId);
+        if (options.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options.offset !== undefined)
+            params.set("offset", String(options.offset));
+        const query = params.toString();
+        const response = await this.request("GET", `/v1/threads${query ? `?${query}` : ""}`);
+        return response.threads;
+    }
+    async getThread(threadId, workspaceId) {
+        const params = new URLSearchParams();
+        const wsId = workspaceId ?? this.workspaceId;
+        if (wsId)
+            params.set("workspace_id", wsId);
+        const query = params.toString();
+        const response = await this.request("GET", `/v1/threads/${threadId}${query ? `?${query}` : ""}`);
+        return response.thread;
+    }
+    async getThreadFull(threadId, options) {
+        const params = new URLSearchParams();
+        const wsId = options?.workspaceId ?? this.workspaceId;
+        if (wsId)
+            params.set("workspace_id", wsId);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options?.offset !== undefined)
+            params.set("offset", String(options.offset));
+        if (options?.order)
+            params.set("order", options.order);
+        const query = params.toString();
+        return this.request("GET", `/v1/threads/${threadId}/full${query ? `?${query}` : ""}`);
+    }
+    async deleteThread(threadId, workspaceId) {
+        const params = new URLSearchParams();
+        const wsId = workspaceId ?? this.workspaceId;
+        if (wsId)
+            params.set("workspace_id", wsId);
+        const query = params.toString();
+        await this.request("DELETE", `/v1/threads/${threadId}${query ? `?${query}` : ""}`);
+    }
+    async appendMessages(threadId, messages, workspaceId) {
+        const params = new URLSearchParams();
+        const wsId = workspaceId ?? this.workspaceId;
+        if (wsId)
+            params.set("workspace_id", wsId);
+        const query = params.toString();
+        return this.request("POST", `/v1/threads/${threadId}/messages${query ? `?${query}` : ""}`, { messages });
+    }
+    async getMessages(threadId, options) {
+        const params = new URLSearchParams();
+        const wsId = options?.workspaceId ?? this.workspaceId;
+        if (wsId)
+            params.set("workspace_id", wsId);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options?.offset !== undefined)
+            params.set("offset", String(options.offset));
+        if (options?.afterIndex !== undefined)
+            params.set("after_index", String(options.afterIndex));
+        if (options?.order)
+            params.set("order", options.order);
+        const query = params.toString();
+        return this.request("GET", `/v1/threads/${threadId}/messages${query ? `?${query}` : ""}`);
+    }
+    async decomposeThread(threadId, workspaceId) {
+        const params = new URLSearchParams();
+        const wsId = workspaceId ?? this.workspaceId;
+        if (wsId)
+            params.set("workspace_id", wsId);
+        const query = params.toString();
+        return this.request("POST", `/v1/threads/${threadId}/decompose${query ? `?${query}` : ""}`);
+    }
+    // ------------------------------------------------------------------ //
+    // Dataset operations (Enterprise)
+    // ------------------------------------------------------------------ //
+    /**
+     * Upload a dataset for profiling and memory extraction.
+     *
+     * Requires MemoryLayer Enterprise. On OSS servers this throws
+     * `EnterpriseRequiredError`.
+     */
+    async uploadDataset(file, filename, options = {}) {
+        const formData = new FormData();
+        formData.append("file", file, filename);
+        if (options.name)
+            formData.append("name", options.name);
+        if (options.targetContextId)
+            formData.append("target_context_id", options.targetContextId);
+        if (options.importance !== undefined)
+            formData.append("importance", String(options.importance));
+        if (options.sampleRows !== undefined)
+            formData.append("sample_rows", String(options.sampleRows));
+        if (options.detectTimeSeries !== undefined)
+            formData.append("detect_time_series", String(options.detectTimeSeries));
+        if (options.generateSummaries !== undefined)
+            formData.append("generate_summaries", String(options.generateSummaries));
+        const headers = {};
+        if (this.apiKey)
+            headers["Authorization"] = `Bearer ${this.apiKey}`;
+        if (this.sessionId)
+            headers["X-Session-ID"] = this.sessionId;
+        if (this.workspaceId)
+            headers["X-Workspace-ID"] = this.workspaceId;
+        const url = `${this.baseUrl}/v1/datasets`;
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        try {
+            const response = await fetch(url, {
+                method: "POST",
+                headers,
+                body: formData,
+                signal: controller.signal,
+            });
+            clearTimeout(timeoutId);
+            if (!response.ok) {
+                await this.handleError(response, "Dataset management");
+            }
+            return await response.json();
+        }
+        catch (error) {
+            if (error instanceof MemoryLayerError)
+                throw error;
+            throw new MemoryLayerError(`Dataset upload failed: ${error}`);
+        }
+    }
+    /**
+     * List datasets in the workspace.
+     */
+    async listDatasets(options) {
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set("status", options.status);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        if (options?.offset !== undefined)
+            params.set("offset", String(options.offset));
+        const query = params.toString();
+        return this.request("GET", `/v1/datasets${query ? `?${query}` : ""}`, undefined, "Dataset management");
+    }
+    /**
+     * Get dataset metadata, schema, and profile.
+     */
+    async getDataset(datasetId) {
+        return this.request("GET", `/v1/datasets/${datasetId}`, undefined, "Dataset management");
+    }
+    /**
+     * Delete a dataset and optionally its extracted memories.
+     */
+    async deleteDataset(datasetId, deleteMemories = false) {
+        await this.request("DELETE", `/v1/datasets/${datasetId}?delete_memories=${deleteMemories}`, undefined, "Dataset management");
+    }
+    /**
+     * Get memories extracted from a dataset.
+     */
+    async getDatasetMemories(datasetId) {
+        return this.request("GET", `/v1/datasets/${datasetId}/memories`, undefined, "Dataset management");
+    }
+    /**
+     * Query a slice of dataset data using DuckDB.
+     *
+     * Supports both structured filters and raw SQL (SELECT only).
+     * The dataset is queried as a table named 'data'.
+     */
+    async queryDatasetSlice(datasetId, options = {}) {
+        const body = {
+            limit: options.limit ?? 100,
+            offset: options.offset ?? 0,
+            descending: options.descending ?? false,
+        };
+        if (options.sql !== undefined)
+            body.sql = options.sql;
+        if (options.columns !== undefined)
+            body.columns = options.columns;
+        if (options.filters !== undefined)
+            body.filters = options.filters;
+        if (options.orderBy !== undefined)
+            body.order_by = options.orderBy;
+        return this.request("POST", `/v1/datasets/${datasetId}/slice`, body, "Dataset management");
+    }
+    /**
+     * Get dataset processing job status.
+     */
+    async getDatasetJob(jobId) {
+        return this.request("GET", `/v1/datasets/jobs/${jobId}`, undefined, "Dataset processing jobs");
+    }
+    /**
+     * List dataset processing jobs in the workspace.
+     */
+    async listDatasetJobs(options) {
+        const params = new URLSearchParams();
+        if (options?.status)
+            params.set("status", options.status);
+        if (options?.limit !== undefined)
+            params.set("limit", String(options.limit));
+        const query = params.toString();
+        return this.request("GET", `/v1/datasets/jobs${query ? `?${query}` : ""}`, undefined, "Dataset processing jobs");
+    }
+    /**
+     * Cancel a running dataset processing job.
+     */
+    async cancelDatasetJob(jobId) {
+        await this.request("POST", `/v1/datasets/jobs/${jobId}/cancel`, undefined, "Dataset processing jobs");
+    }
+    /** Used internally by SkillsNamespace to make requests with OBO authority. */
+    async _skillsRequest(method, path, body, authority) {
+        return this.request(method, path, body, undefined, authority);
+    }
+    /** Used internally by McpServersNamespace to make requests with OBO authority. */
+    async _mcpServersRequest(method, path, body, authority) {
+        return this.request(method, path, body, undefined, authority);
+    }
+}
+/**
+ * Lightweight OBO proxy returned by `client.actingFor()`.
+ * Delegates all calls to the parent client with a fixed AuthorityContext and
+ * optional workspace override. Per-call authority headers are computed fresh
+ * on each request — no shared mutable state, so concurrent calls for different
+ * subjects on the same underlying client never interfere.
+ */
+export class OboProxy {
+    _client;
+    _authority;
+    _workspaceId;
+    /** Skills namespace scoped to this proxy's authority. */
+    skills;
+    /** MCP Servers namespace scoped to this proxy's authority. */
+    mcpServers;
+    constructor(client, authority, workspaceId) {
+        this._client = client;
+        this._authority = authority;
+        this._workspaceId = workspaceId;
+        this.skills = new SkillsNamespace(client, authority, workspaceId);
+        this.mcpServers = new McpServersNamespace(client, authority, workspaceId);
+    }
+    /** Further scope this proxy to a single workspace. */
+    forWorkspace(workspaceId) {
+        return new OboProxy(this._client, this._authority, workspaceId);
+    }
+    async remember(content, options = {}) {
+        return this._client.remember(content, {
+            ...options,
+            workspaceId: options.workspaceId ?? this._workspaceId,
+            authority: options.authority ?? this._authority,
+        });
+    }
+    async recall(query, options = {}) {
+        return this._client.recall(query, {
+            ...options,
+            workspaceId: options.workspaceId ?? this._workspaceId,
+            authority: options.authority ?? this._authority,
+        });
+    }
+    async reflect(query, options = {}) {
+        return this._client.reflect(query, {
+            ...options,
+            workspaceId: options.workspaceId ?? this._workspaceId,
+            authority: options.authority ?? this._authority,
+        });
+    }
 }
 //# sourceMappingURL=client.js.map