@usetransactional/memory 1.0.0

package/dist/index.js

@@ -0,0 +1,592 @@
+// src/errors.ts
+var MemoryError = class extends Error {
+  /** Error code */
+  code;
+  /** HTTP status code */
+  status;
+  /** Additional error details */
+  details;
+  constructor(message, code, status, details) {
+    super(message);
+    this.name = "MemoryError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+var AuthenticationError = class extends MemoryError {
+  constructor(message = "Invalid or missing API key") {
+    super(message, "AUTHENTICATION_ERROR", 401);
+    this.name = "AuthenticationError";
+  }
+};
+var ValidationError = class extends MemoryError {
+  /** Field-level errors */
+  fieldErrors;
+  constructor(message, fieldErrors) {
+    super(message, "VALIDATION_ERROR", 400, { fieldErrors });
+    this.name = "ValidationError";
+    this.fieldErrors = fieldErrors;
+  }
+};
+var NotFoundError = class extends MemoryError {
+  /** Resource type */
+  resourceType;
+  /** Resource ID */
+  resourceId;
+  constructor(resourceType, resourceId) {
+    const message = resourceId ? `${resourceType} with ID '${resourceId}' not found` : `${resourceType} not found`;
+    super(message, "NOT_FOUND", 404, { resourceType, resourceId });
+    this.name = "NotFoundError";
+    this.resourceType = resourceType;
+    this.resourceId = resourceId;
+  }
+};
+var RateLimitError = class extends MemoryError {
+  /** Time to wait before retrying (seconds) */
+  retryAfter;
+  /** Rate limit */
+  limit;
+  /** Remaining requests */
+  remaining;
+  /** Reset timestamp */
+  reset;
+  constructor(retryAfter, options) {
+    super(
+      `Rate limit exceeded. Retry after ${retryAfter} seconds.`,
+      "RATE_LIMIT_ERROR",
+      429,
+      { retryAfter, ...options }
+    );
+    this.name = "RateLimitError";
+    this.retryAfter = retryAfter;
+    this.limit = options?.limit;
+    this.remaining = options?.remaining;
+    this.reset = options?.reset;
+  }
+};
+var ServerError = class extends MemoryError {
+  constructor(message = "Internal server error", details) {
+    super(message, "SERVER_ERROR", 500, details);
+    this.name = "ServerError";
+  }
+};
+var TimeoutError = class extends MemoryError {
+  /** Timeout duration in ms */
+  timeout;
+  constructor(timeout) {
+    super(
+      `Request timed out after ${timeout}ms`,
+      "TIMEOUT_ERROR",
+      408,
+      { timeout }
+    );
+    this.name = "TimeoutError";
+    this.timeout = timeout;
+  }
+};
+var NetworkError = class extends MemoryError {
+  constructor(message = "Network request failed", details) {
+    super(message, "NETWORK_ERROR", 0, details);
+    this.name = "NetworkError";
+  }
+};
+function parseApiError(status, body) {
+  const errorBody = typeof body === "string" ? { message: body } : body;
+  const message = errorBody.message || "Unknown error";
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message);
+    case 400:
+    case 422:
+      return new ValidationError(
+        message,
+        errorBody.errors
+      );
+    case 404:
+      return new NotFoundError("Resource", void 0);
+    case 429:
+      return new RateLimitError(60);
+    // Default to 60 seconds
+    case 500:
+    case 502:
+    case 503:
+    case 504:
+      return new ServerError(message, errorBody);
+    default:
+      return new MemoryError(message, "UNKNOWN_ERROR", status, errorBody);
+  }
+}
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.usetransactional.com";
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var MemoryClient = class {
+  apiKey;
+  baseUrl;
+  timeout;
+  maxRetries;
+  customHeaders;
+  /** Session operations */
+  sessions;
+  /** Profile operations */
+  profiles;
+  /** Graph operations */
+  graph;
+  /** Ingest operations */
+  ingest;
+  constructor(config) {
+    if (!config.apiKey) {
+      throw new AuthenticationError("API key is required");
+    }
+    this.apiKey = config.apiKey;
+    this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, "");
+    this.timeout = config.timeout ?? DEFAULT_TIMEOUT;
+    this.maxRetries = config.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.customHeaders = config.headers || {};
+    this.sessions = new SessionOperations(this);
+    this.profiles = new ProfileOperations(this);
+    this.graph = new GraphOperations(this);
+    this.ingest = new IngestOperations(this);
+  }
+  // ===========================================
+  // HTTP METHODS
+  // ===========================================
+  /**
+   * Make an HTTP request to the API.
+   */
+  async request(options) {
+    const url = `${this.baseUrl}${options.path}`;
+    const timeout = options.timeout ?? this.timeout;
+    const headers = {
+      "X-API-Key": this.apiKey,
+      "Content-Type": "application/json",
+      "Accept": "application/json",
+      ...this.customHeaders,
+      ...options.headers
+    };
+    let lastError = null;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeout);
+        try {
+          const response = await fetch(url, {
+            method: options.method,
+            headers,
+            body: options.body ? JSON.stringify(options.body) : void 0,
+            signal: controller.signal
+          });
+          clearTimeout(timeoutId);
+          const text = await response.text();
+          let body;
+          try {
+            body = text ? JSON.parse(text) : {};
+          } catch {
+            body = { message: text };
+          }
+          if (!response.ok) {
+            const error = parseApiError(response.status, body);
+            if (response.status < 500 && response.status !== 429) {
+              throw error;
+            }
+            if (response.status === 429) {
+              const retryAfter = parseInt(
+                response.headers.get("Retry-After") || "60",
+                10
+              );
+              if (attempt < this.maxRetries) {
+                await this.sleep(retryAfter * 1e3);
+                continue;
+              }
+              throw new RateLimitError(retryAfter);
+            }
+            lastError = error;
+            if (attempt < this.maxRetries) {
+              await this.sleep(Math.pow(2, attempt) * 1e3);
+              continue;
+            }
+            throw error;
+          }
+          const apiResponse = body;
+          return apiResponse.data;
+        } finally {
+          clearTimeout(timeoutId);
+        }
+      } catch (error) {
+        if (error instanceof MemoryError) {
+          throw error;
+        }
+        if (error instanceof Error) {
+          if (error.name === "AbortError") {
+            throw new TimeoutError(timeout);
+          }
+          lastError = new NetworkError(error.message);
+        }
+        if (attempt < this.maxRetries) {
+          await this.sleep(Math.pow(2, attempt) * 1e3);
+          continue;
+        }
+        throw lastError || new NetworkError("Request failed");
+      }
+    }
+    throw lastError || new NetworkError("Request failed after retries");
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+  // ===========================================
+  // MEMORY OPERATIONS
+  // ===========================================
+  /**
+   * Add a memory.
+   */
+  async add(params) {
+    return this.request({
+      method: "POST",
+      path: "/memory/ingest",
+      body: {
+        content: params.content,
+        sessionId: params.sessionId,
+        metadata: {
+          ...params.metadata,
+          userId: params.userId,
+          type: params.type
+        }
+      }
+    });
+  }
+  /**
+   * Search memories.
+   */
+  async search(params) {
+    return this.request({
+      method: "POST",
+      path: params.sessionId ? `/memory/sessions/${params.sessionId}/search` : "/memory/search/global",
+      body: {
+        query: params.query,
+        sessionIds: params.sessionIds,
+        userId: params.userId,
+        types: params.types,
+        strategy: params.strategy,
+        threshold: params.threshold,
+        limit: params.limit,
+        includeRelated: params.includeRelated
+      }
+    });
+  }
+  /**
+   * Get a specific memory by ID.
+   */
+  async get(sessionId, memoryId) {
+    return this.request({
+      method: "GET",
+      path: `/memory/sessions/${sessionId}/entities/${memoryId}`
+    });
+  }
+  /**
+   * Update a memory.
+   */
+  async update(sessionId, memoryId, params) {
+    return this.request({
+      method: "PATCH",
+      path: `/memory/sessions/${sessionId}/entities/${memoryId}`,
+      body: params
+    });
+  }
+  /**
+   * Delete a memory.
+   */
+  async delete(sessionId, memoryId) {
+    await this.request({
+      method: "DELETE",
+      path: `/memory/sessions/${sessionId}/entities/${memoryId}`
+    });
+  }
+  /**
+   * Get context for LLM prompts.
+   */
+  async getContext(params) {
+    const queryParams = new URLSearchParams();
+    if (params.query) queryParams.set("query", params.query);
+    if (params.maxTokens) queryParams.set("maxTokens", params.maxTokens.toString());
+    if (params.includeProfile !== void 0)
+      queryParams.set("includeProfile", params.includeProfile.toString());
+    if (params.includeFacts !== void 0)
+      queryParams.set("includeFacts", params.includeFacts.toString());
+    if (params.includePreferences !== void 0)
+      queryParams.set("includePreferences", params.includePreferences.toString());
+    const path = params.sessionId ? `/memory/sessions/${params.sessionId}/context` : `/memory/profiles/${params.userId}/context`;
+    return this.request({
+      method: "GET",
+      path: `${path}?${queryParams.toString()}`
+    });
+  }
+  /**
+   * Get job status.
+   */
+  async getJobStatus(jobId) {
+    return this.request({
+      method: "GET",
+      path: `/memory/jobs/${jobId}`
+    });
+  }
+};
+var SessionOperations = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Create a new session.
+   */
+  async create(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/memory/sessions",
+      body: params
+    });
+  }
+  /**
+   * Get a session by ID.
+   */
+  async get(sessionId) {
+    return this.client.request({
+      method: "GET",
+      path: `/memory/sessions/${sessionId}`
+    });
+  }
+  /**
+   * List sessions.
+   */
+  async list(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.status) queryParams.set("status", params.status);
+    if (params?.agentId) queryParams.set("agentId", params.agentId);
+    if (params?.userId) queryParams.set("userId", params.userId);
+    if (params?.search) queryParams.set("search", params.search);
+    if (params?.page) queryParams.set("page", params.page.toString());
+    if (params?.limit) queryParams.set("limit", params.limit.toString());
+    return this.client.request({
+      method: "GET",
+      path: `/memory/sessions?${queryParams.toString()}`
+    });
+  }
+  /**
+   * Update a session.
+   */
+  async update(sessionId, params) {
+    return this.client.request({
+      method: "PATCH",
+      path: `/memory/sessions/${sessionId}`,
+      body: params
+    });
+  }
+  /**
+   * Delete a session.
+   */
+  async delete(sessionId) {
+    await this.client.request({
+      method: "DELETE",
+      path: `/memory/sessions/${sessionId}`
+    });
+  }
+};
+var ProfileOperations = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get a user profile.
+   */
+  async get(userId) {
+    return this.client.request({
+      method: "GET",
+      path: `/memory/profiles/${userId}`
+    });
+  }
+  /**
+   * Create or update a user profile.
+   */
+  async upsert(userId, params) {
+    return this.client.request({
+      method: "POST",
+      path: `/memory/profiles/${userId}`,
+      body: params
+    });
+  }
+  /**
+   * Delete a user profile.
+   */
+  async delete(userId) {
+    await this.client.request({
+      method: "DELETE",
+      path: `/memory/profiles/${userId}`
+    });
+  }
+};
+var GraphOperations = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Get the knowledge graph.
+   */
+  async get(params) {
+    const queryParams = new URLSearchParams();
+    if (params?.centerEntityId)
+      queryParams.set("centerEntityId", params.centerEntityId);
+    if (params?.depth) queryParams.set("depth", params.depth.toString());
+    if (params?.entityTypes)
+      queryParams.set("entityTypes", params.entityTypes.join(","));
+    if (params?.edgeTypes)
+      queryParams.set("edgeTypes", params.edgeTypes.join(","));
+    if (params?.minWeight)
+      queryParams.set("minWeight", params.minWeight.toString());
+    if (params?.limit) queryParams.set("limit", params.limit.toString());
+    const path = params?.sessionId ? `/memory/sessions/${params.sessionId}/graph` : "/memory/graph";
+    return this.client.request({
+      method: "GET",
+      path: `${path}?${queryParams.toString()}`
+    });
+  }
+  /**
+   * Traverse the graph from a starting entity.
+   */
+  async traverse(params) {
+    const queryParams = new URLSearchParams();
+    queryParams.set("startEntityId", params.startEntityId);
+    if (params.depth) queryParams.set("depth", params.depth.toString());
+    if (params.direction) queryParams.set("direction", params.direction);
+    if (params.entityTypes)
+      queryParams.set("entityTypes", params.entityTypes.join(","));
+    if (params.edgeTypes)
+      queryParams.set("edgeTypes", params.edgeTypes.join(","));
+    if (params.minWeight)
+      queryParams.set("minWeight", params.minWeight.toString());
+    if (params.limit) queryParams.set("limit", params.limit.toString());
+    return this.client.request({
+      method: "GET",
+      path: `/memory/graph/traverse?${queryParams.toString()}`
+    });
+  }
+};
+var IngestOperations = class {
+  constructor(client) {
+    this.client = client;
+  }
+  /**
+   * Ingest URL content.
+   */
+  async url(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/memory/ingest/url",
+      body: params
+    });
+  }
+  /**
+   * Ingest PDF content.
+   */
+  async pdf(params) {
+    const formData = new FormData();
+    if (Buffer.isBuffer(params.file)) {
+      const blob = new Blob([params.file], { type: "application/pdf" });
+      formData.append("file", blob, params.filename);
+    } else {
+      formData.append("file", params.file, params.filename);
+    }
+    const options = {
+      sessionId: params.sessionId,
+      userId: params.userId,
+      metadata: params.metadata,
+      extractEntities: params.options?.extractEntities,
+      generateEmbeddings: params.options?.generateEmbeddings,
+      ocrFallback: params.options?.ocrFallback
+    };
+    formData.append("options", JSON.stringify(options));
+    const url = `${this.client.baseUrl}/memory/ingest/pdf`;
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "X-API-Key": this.client.apiKey
+      },
+      body: formData
+    });
+    if (!response.ok) {
+      const text = await response.text();
+      let body;
+      try {
+        body = JSON.parse(text);
+      } catch {
+        body = { message: text };
+      }
+      throw parseApiError(response.status, body);
+    }
+    const result = await response.json();
+    return result.data;
+  }
+  /**
+   * Ingest text content.
+   */
+  async text(params) {
+    return this.client.request({
+      method: "POST",
+      path: "/memory/ingest",
+      body: {
+        content: params.content,
+        contentType: params.contentType,
+        sessionId: params.sessionId,
+        metadata: params.metadata
+      }
+    });
+  }
+};
+
+// src/types.ts
+var MemoryEntityType = /* @__PURE__ */ ((MemoryEntityType2) => {
+  MemoryEntityType2["USER"] = "user";
+  MemoryEntityType2["FACT"] = "fact";
+  MemoryEntityType2["TOPIC"] = "topic";
+  MemoryEntityType2["PREFERENCE"] = "preference";
+  MemoryEntityType2["EVENT"] = "event";
+  MemoryEntityType2["MESSAGE"] = "message";
+  MemoryEntityType2["SUMMARY"] = "summary";
+  MemoryEntityType2["ORGANIZATION"] = "organization";
+  return MemoryEntityType2;
+})(MemoryEntityType || {});
+var MemoryEdgeType = /* @__PURE__ */ ((MemoryEdgeType2) => {
+  MemoryEdgeType2["PREFERS"] = "prefers";
+  MemoryEdgeType2["MENTIONED"] = "mentioned";
+  MemoryEdgeType2["DISCUSSED"] = "discussed";
+  MemoryEdgeType2["ASKED_ABOUT"] = "asked_about";
+  MemoryEdgeType2["RELATES_TO"] = "relates_to";
+  MemoryEdgeType2["FOLLOWS_UP"] = "follows_up";
+  MemoryEdgeType2["SUMMARIZES"] = "summarizes";
+  MemoryEdgeType2["EXTRACTED_FROM"] = "extracted_from";
+  MemoryEdgeType2["WORKS_AT"] = "works_at";
+  MemoryEdgeType2["INTERESTED_IN"] = "interested_in";
+  return MemoryEdgeType2;
+})(MemoryEdgeType || {});
+var MemoryFactSource = /* @__PURE__ */ ((MemoryFactSource2) => {
+  MemoryFactSource2["EXTRACTED"] = "extracted";
+  MemoryFactSource2["EXPLICIT"] = "explicit";
+  MemoryFactSource2["INFERRED"] = "inferred";
+  return MemoryFactSource2;
+})(MemoryFactSource || {});
+var MemorySessionStatus = /* @__PURE__ */ ((MemorySessionStatus2) => {
+  MemorySessionStatus2["ACTIVE"] = "ACTIVE";
+  MemorySessionStatus2["EXPIRED"] = "EXPIRED";
+  MemorySessionStatus2["DELETED"] = "DELETED";
+  return MemorySessionStatus2;
+})(MemorySessionStatus || {});
+var MemoryMessageRole = /* @__PURE__ */ ((MemoryMessageRole2) => {
+  MemoryMessageRole2["USER"] = "user";
+  MemoryMessageRole2["ASSISTANT"] = "assistant";
+  MemoryMessageRole2["SYSTEM"] = "system";
+  return MemoryMessageRole2;
+})(MemoryMessageRole || {});
+
+export { AuthenticationError, MemoryClient, MemoryEdgeType, MemoryEntityType, MemoryError, MemoryFactSource, MemoryMessageRole, MemorySessionStatus, NetworkError, NotFoundError, RateLimitError, ServerError, TimeoutError, ValidationError };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map