mem0ai 2.4.0 → 2.4.2

package/dist/index.d.mts

@@ -154,7 +154,8 @@ interface PromptUpdatePayload {
 declare enum WebhookEvent {
     MEMORY_ADDED = "memory_add",
     MEMORY_UPDATED = "memory_update",
-    MEMORY_DELETED = "memory_delete"
+    MEMORY_DELETED = "memory_delete",
+    MEMORY_CATEGORIZED = "memory_categorize"
 }
 interface Webhook {
     webhook_id?: string;
@@ -166,12 +167,16 @@ interface Webhook {
     is_active?: boolean;
     event_types?: WebhookEvent[];
 }
-interface WebhookPayload {
-    eventTypes: WebhookEvent[];
-    projectId: string;
-    webhookId: string;
+interface WebhookCreatePayload {
     name: string;
     url: string;
+    eventTypes: WebhookEvent[];
+}
+interface WebhookUpdatePayload {
+    webhookId: string;
+    name?: string;
+    url?: string;
+    eventTypes?: WebhookEvent[];
 }
 interface FeedbackPayload {
     memory_id: string;
@@ -256,8 +261,8 @@ declare class MemoryClient {
     getWebhooks(data?: {
         projectId?: string;
     }): Promise<Array<Webhook>>;
-    createWebhook(webhook: WebhookPayload): Promise<Webhook>;
-    updateWebhook(webhook: WebhookPayload): Promise<{
+    createWebhook(webhook: WebhookCreatePayload): Promise<Webhook>;
+    updateWebhook(webhook: WebhookUpdatePayload): Promise<{
         message: string;
     }>;
     deleteWebhook(data: {
@@ -278,4 +283,81 @@ declare class MemoryClient {
     }>;
 }
 
-export { type AllUsers, Feedback, type FeedbackPayload, type Memory, MemoryClient, type MemoryHistory, type MemoryOptions, type MemoryUpdateBody, type Message, type Messages, type ProjectOptions, type ProjectResponse, type PromptUpdatePayload, type SearchOptions, type User, type Webhook, type WebhookPayload, MemoryClient as default };
+/**
+ * Structured exception classes for mem0 TypeScript SDK.
+ *
+ * Provides specific, actionable exceptions with error codes, suggestions,
+ * and debug information. Maps HTTP status codes to appropriate exception types.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimitError, MemoryNotFoundError } from 'mem0ai'
+ *
+ * try {
+ *   await client.get(memoryId)
+ * } catch (e) {
+ *   if (e instanceof MemoryNotFoundError) {
+ *     console.log(e.suggestion) // "The requested resource was not found"
+ *   } else if (e instanceof RateLimitError) {
+ *     await sleep(e.debugInfo.retryAfter ?? 60)
+ *   }
+ * }
+ * ```
+ */
+interface MemoryErrorOptions {
+    details?: Record<string, unknown>;
+    suggestion?: string;
+    debugInfo?: Record<string, unknown>;
+}
+/**
+ * Base exception for all memory-related errors.
+ *
+ * Every mem0 exception includes an error code for programmatic handling,
+ * optional details, a user-friendly suggestion, and debug information.
+ */
+declare class MemoryError extends Error {
+    readonly errorCode: string;
+    readonly details: Record<string, unknown>;
+    readonly suggestion?: string;
+    readonly debugInfo: Record<string, unknown>;
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when authentication fails (401, 403). */
+declare class AuthenticationError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when rate limits are exceeded (429). */
+declare class RateLimitError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when input validation fails (400, 409, 422). */
+declare class ValidationError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when a memory is not found (404). */
+declare class MemoryNotFoundError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when network connectivity issues occur (408, 502, 503, 504). */
+declare class NetworkError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when client configuration is invalid. */
+declare class ConfigurationError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when memory quota is exceeded (413). */
+declare class MemoryQuotaExceededError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/**
+ * Create an appropriate exception based on HTTP response status code.
+ *
+ * @param statusCode - HTTP status code from the response
+ * @param responseText - Response body text
+ * @param options - Additional error context (details, debugInfo)
+ * @returns An instance of the appropriate MemoryError subclass
+ */
+declare function createExceptionFromResponse(statusCode: number, responseText: string, options?: Omit<MemoryErrorOptions, "suggestion">): MemoryError;
+
+export { type AllUsers, AuthenticationError, ConfigurationError, Feedback, type FeedbackPayload, type Memory, MemoryClient, MemoryError, type MemoryErrorOptions, type MemoryHistory, MemoryNotFoundError, type MemoryOptions, MemoryQuotaExceededError, type MemoryUpdateBody, type Message, type Messages, NetworkError, type ProjectOptions, type ProjectResponse, type PromptUpdatePayload, RateLimitError, type SearchOptions, type User, ValidationError, type Webhook, type WebhookCreatePayload, WebhookEvent, type WebhookUpdatePayload, createExceptionFromResponse, MemoryClient as default };

package/dist/index.d.ts

@@ -154,7 +154,8 @@ interface PromptUpdatePayload {
 declare enum WebhookEvent {
     MEMORY_ADDED = "memory_add",
     MEMORY_UPDATED = "memory_update",
-    MEMORY_DELETED = "memory_delete"
+    MEMORY_DELETED = "memory_delete",
+    MEMORY_CATEGORIZED = "memory_categorize"
 }
 interface Webhook {
     webhook_id?: string;
@@ -166,12 +167,16 @@ interface Webhook {
     is_active?: boolean;
     event_types?: WebhookEvent[];
 }
-interface WebhookPayload {
-    eventTypes: WebhookEvent[];
-    projectId: string;
-    webhookId: string;
+interface WebhookCreatePayload {
     name: string;
     url: string;
+    eventTypes: WebhookEvent[];
+}
+interface WebhookUpdatePayload {
+    webhookId: string;
+    name?: string;
+    url?: string;
+    eventTypes?: WebhookEvent[];
 }
 interface FeedbackPayload {
     memory_id: string;
@@ -256,8 +261,8 @@ declare class MemoryClient {
     getWebhooks(data?: {
         projectId?: string;
     }): Promise<Array<Webhook>>;
-    createWebhook(webhook: WebhookPayload): Promise<Webhook>;
-    updateWebhook(webhook: WebhookPayload): Promise<{
+    createWebhook(webhook: WebhookCreatePayload): Promise<Webhook>;
+    updateWebhook(webhook: WebhookUpdatePayload): Promise<{
         message: string;
     }>;
     deleteWebhook(data: {
@@ -278,4 +283,81 @@ declare class MemoryClient {
     }>;
 }
 
-export { type AllUsers, Feedback, type FeedbackPayload, type Memory, MemoryClient, type MemoryHistory, type MemoryOptions, type MemoryUpdateBody, type Message, type Messages, type ProjectOptions, type ProjectResponse, type PromptUpdatePayload, type SearchOptions, type User, type Webhook, type WebhookPayload, MemoryClient as default };
+/**
+ * Structured exception classes for mem0 TypeScript SDK.
+ *
+ * Provides specific, actionable exceptions with error codes, suggestions,
+ * and debug information. Maps HTTP status codes to appropriate exception types.
+ *
+ * @example
+ * ```typescript
+ * import { RateLimitError, MemoryNotFoundError } from 'mem0ai'
+ *
+ * try {
+ *   await client.get(memoryId)
+ * } catch (e) {
+ *   if (e instanceof MemoryNotFoundError) {
+ *     console.log(e.suggestion) // "The requested resource was not found"
+ *   } else if (e instanceof RateLimitError) {
+ *     await sleep(e.debugInfo.retryAfter ?? 60)
+ *   }
+ * }
+ * ```
+ */
+interface MemoryErrorOptions {
+    details?: Record<string, unknown>;
+    suggestion?: string;
+    debugInfo?: Record<string, unknown>;
+}
+/**
+ * Base exception for all memory-related errors.
+ *
+ * Every mem0 exception includes an error code for programmatic handling,
+ * optional details, a user-friendly suggestion, and debug information.
+ */
+declare class MemoryError extends Error {
+    readonly errorCode: string;
+    readonly details: Record<string, unknown>;
+    readonly suggestion?: string;
+    readonly debugInfo: Record<string, unknown>;
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when authentication fails (401, 403). */
+declare class AuthenticationError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when rate limits are exceeded (429). */
+declare class RateLimitError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when input validation fails (400, 409, 422). */
+declare class ValidationError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when a memory is not found (404). */
+declare class MemoryNotFoundError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when network connectivity issues occur (408, 502, 503, 504). */
+declare class NetworkError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when client configuration is invalid. */
+declare class ConfigurationError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/** Raised when memory quota is exceeded (413). */
+declare class MemoryQuotaExceededError extends MemoryError {
+    constructor(message: string, errorCode: string, options?: MemoryErrorOptions);
+}
+/**
+ * Create an appropriate exception based on HTTP response status code.
+ *
+ * @param statusCode - HTTP status code from the response
+ * @param responseText - Response body text
+ * @param options - Additional error context (details, debugInfo)
+ * @returns An instance of the appropriate MemoryError subclass
+ */
+declare function createExceptionFromResponse(statusCode: number, responseText: string, options?: Omit<MemoryErrorOptions, "suggestion">): MemoryError;
+
+export { type AllUsers, AuthenticationError, ConfigurationError, Feedback, type FeedbackPayload, type Memory, MemoryClient, MemoryError, type MemoryErrorOptions, type MemoryHistory, MemoryNotFoundError, type MemoryOptions, MemoryQuotaExceededError, type MemoryUpdateBody, type Message, type Messages, NetworkError, type ProjectOptions, type ProjectResponse, type PromptUpdatePayload, RateLimitError, type SearchOptions, type User, ValidationError, type Webhook, type WebhookCreatePayload, WebhookEvent, type WebhookUpdatePayload, createExceptionFromResponse, MemoryClient as default };

package/dist/index.js

@@ -30,7 +30,18 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/client/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  ConfigurationError: () => ConfigurationError,
+  Feedback: () => Feedback,
   MemoryClient: () => MemoryClient,
+  MemoryError: () => MemoryError,
+  MemoryNotFoundError: () => MemoryNotFoundError,
+  MemoryQuotaExceededError: () => MemoryQuotaExceededError,
+  NetworkError: () => NetworkError,
+  RateLimitError: () => RateLimitError,
+  ValidationError: () => ValidationError,
+  WebhookEvent: () => WebhookEvent,
+  createExceptionFromResponse: () => createExceptionFromResponse,
   default: () => index_default
 });
 module.exports = __toCommonJS(index_exports);
@@ -112,6 +123,103 @@ async function captureClientEvent(eventName, instance, additionalData = {}) {
   );
 }
 
+// src/common/exceptions.ts
+var MemoryError = class extends Error {
+  constructor(message, errorCode, options = {}) {
+    var _a2, _b;
+    super(message);
+    this.name = "MemoryError";
+    this.errorCode = errorCode;
+    this.details = (_a2 = options.details) != null ? _a2 : {};
+    this.suggestion = options.suggestion;
+    this.debugInfo = (_b = options.debugInfo) != null ? _b : {};
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends MemoryError {
+  constructor(message, errorCode, options) {
+    super(message, errorCode, options);
+    this.name = "AuthenticationError";
+  }
+};
+var RateLimitError = class extends MemoryError {
+  constructor(message, errorCode, options) {
+    super(message, errorCode, options);
+    this.name = "RateLimitError";
+  }
+};
+var ValidationError = class extends MemoryError {
+  constructor(message, errorCode, options) {
+    super(message, errorCode, options);
+    this.name = "ValidationError";
+  }
+};
+var MemoryNotFoundError = class extends MemoryError {
+  constructor(message, errorCode, options) {
+    super(message, errorCode, options);
+    this.name = "MemoryNotFoundError";
+  }
+};
+var NetworkError = class extends MemoryError {
+  constructor(message, errorCode, options) {
+    super(message, errorCode, options);
+    this.name = "NetworkError";
+  }
+};
+var ConfigurationError = class extends MemoryError {
+  constructor(message, errorCode, options) {
+    super(message, errorCode, options);
+    this.name = "ConfigurationError";
+  }
+};
+var MemoryQuotaExceededError = class extends MemoryError {
+  constructor(message, errorCode, options) {
+    super(message, errorCode, options);
+    this.name = "MemoryQuotaExceededError";
+  }
+};
+var HTTP_STATUS_TO_EXCEPTION = {
+  400: ValidationError,
+  401: AuthenticationError,
+  403: AuthenticationError,
+  404: MemoryNotFoundError,
+  408: NetworkError,
+  409: ValidationError,
+  413: MemoryQuotaExceededError,
+  422: ValidationError,
+  429: RateLimitError,
+  500: MemoryError,
+  502: NetworkError,
+  503: NetworkError,
+  504: NetworkError
+};
+var HTTP_SUGGESTIONS = {
+  400: "Please check your request parameters and try again",
+  401: "Please check your API key and authentication credentials",
+  403: "You don't have permission to perform this operation",
+  404: "The requested resource was not found",
+  408: "Request timed out. Please try again",
+  409: "Resource conflict. Please check your request",
+  413: "Request too large. Please reduce the size of your request",
+  422: "Invalid request data. Please check your input",
+  429: "Rate limit exceeded. Please wait before making more requests",
+  500: "Internal server error. Please try again later",
+  502: "Service temporarily unavailable. Please try again later",
+  503: "Service unavailable. Please try again later",
+  504: "Gateway timeout. Please try again later"
+};
+function createExceptionFromResponse(statusCode, responseText, options = {}) {
+  var _a2, _b;
+  const ExceptionClass = (_a2 = HTTP_STATUS_TO_EXCEPTION[statusCode]) != null ? _a2 : MemoryError;
+  const errorCode = `HTTP_${statusCode}`;
+  const suggestion = (_b = HTTP_SUGGESTIONS[statusCode]) != null ? _b : "Please try again later";
+  return new ExceptionClass(
+    responseText || `HTTP ${statusCode} error`,
+    errorCode,
+    { ...options, suggestion }
+  );
+}
+
 // src/client/mem0.ts
 var APIError = class extends Error {
   constructor(message) {
@@ -204,7 +312,7 @@ var MemoryClient = class {
     });
     if (!response.ok) {
       const errorData = await response.text();
-      throw new APIError(`API request failed: ${errorData}`);
+      throw createExceptionFromResponse(response.status, errorData);
     }
     const jsonResponse = await response.json();
     return jsonResponse;
@@ -241,7 +349,7 @@ var MemoryClient = class {
       if (project_id && !this.projectId) this.projectId = project_id;
       if (user_email) this.telemetryId = user_email;
     } catch (error) {
-      if (error instanceof APIError) {
+      if (error instanceof MemoryError || error instanceof APIError) {
         throw error;
       } else {
         throw new APIError(
@@ -322,7 +430,7 @@ var MemoryClient = class {
     this._validateOrgProject();
     const payloadKeys = Object.keys(options || {});
     this._captureEvent("get_all", [payloadKeys]);
-    const { api_version, page, page_size, ...otherOptions } = options;
+    const { api_version, page, page_size, ...otherOptions } = options != null ? options : {};
     if (this.organizationName != null && this.projectName != null) {
       otherOptions.org_name = this.organizationName;
       otherOptions.project_name = this.projectName;
@@ -359,7 +467,7 @@ var MemoryClient = class {
     this._validateOrgProject();
     const payloadKeys = Object.keys(options || {});
     this._captureEvent("search", [payloadKeys]);
-    const { api_version, ...otherOptions } = options;
+    const { api_version, ...otherOptions } = options != null ? options : {};
     const payload = { query, ...otherOptions };
     if (this.organizationName != null && this.projectName != null) {
       payload.org_name = this.organizationName;
@@ -621,12 +729,17 @@ var MemoryClient = class {
   async createWebhook(webhook) {
     if (this.telemetryId === "") await this.ping();
     this._captureEvent("create_webhook", []);
+    const body = {
+      name: webhook.name,
+      url: webhook.url,
+      event_types: webhook.eventTypes
+    };
     const response = await this._fetchWithErrorHandling(
       `${this.host}/api/v1/webhooks/projects/${this.projectId}/`,
       {
         method: "POST",
         headers: this.headers,
-        body: JSON.stringify(webhook)
+        body: JSON.stringify(body)
       }
     );
     return response;
@@ -634,16 +747,16 @@ var MemoryClient = class {
   async updateWebhook(webhook) {
     if (this.telemetryId === "") await this.ping();
     this._captureEvent("update_webhook", []);
-    const project_id = webhook.projectId || this.projectId;
+    const body = {};
+    if (webhook.name != null) body.name = webhook.name;
+    if (webhook.url != null) body.url = webhook.url;
+    if (webhook.eventTypes != null) body.event_types = webhook.eventTypes;
     const response = await this._fetchWithErrorHandling(
       `${this.host}/api/v1/webhooks/${webhook.webhookId}/`,
       {
         method: "PUT",
         headers: this.headers,
-        body: JSON.stringify({
-          ...webhook,
-          projectId: project_id
-        })
+        body: JSON.stringify(body)
       }
     );
     return response;
@@ -715,10 +828,36 @@ var MemoryClient = class {
   }
 };
 
+// src/client/mem0.types.ts
+var Feedback = /* @__PURE__ */ ((Feedback2) => {
+  Feedback2["POSITIVE"] = "POSITIVE";
+  Feedback2["NEGATIVE"] = "NEGATIVE";
+  Feedback2["VERY_NEGATIVE"] = "VERY_NEGATIVE";
+  return Feedback2;
+})(Feedback || {});
+var WebhookEvent = /* @__PURE__ */ ((WebhookEvent2) => {
+  WebhookEvent2["MEMORY_ADDED"] = "memory_add";
+  WebhookEvent2["MEMORY_UPDATED"] = "memory_update";
+  WebhookEvent2["MEMORY_DELETED"] = "memory_delete";
+  WebhookEvent2["MEMORY_CATEGORIZED"] = "memory_categorize";
+  return WebhookEvent2;
+})(WebhookEvent || {});
+
 // src/client/index.ts
 var index_default = MemoryClient;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
-  MemoryClient
+  AuthenticationError,
+  ConfigurationError,
+  Feedback,
+  MemoryClient,
+  MemoryError,
+  MemoryNotFoundError,
+  MemoryQuotaExceededError,
+  NetworkError,
+  RateLimitError,
+  ValidationError,
+  WebhookEvent,
+  createExceptionFromResponse
 });
 //# sourceMappingURL=index.js.map