@maximem/synap-js-sdk 0.1.4 → 0.2.1

package/src/errors.js

@@ -0,0 +1,187 @@
+'use strict';
+
+class SynapError extends Error {
+  constructor(message, correlationId) {
+    super(message);
+    this.name = 'SynapError';
+    this.correlationId = correlationId || null;
+  }
+}
+
+class SynapTransientError extends SynapError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'SynapTransientError';
+  }
+}
+
+class SynapPermanentError extends SynapError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'SynapPermanentError';
+  }
+}
+
+class NetworkTimeoutError extends SynapTransientError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'NetworkTimeoutError';
+  }
+}
+
+class RateLimitError extends SynapTransientError {
+  constructor(message, retryAfterSeconds, correlationId) {
+    super(message, correlationId);
+    this.name = 'RateLimitError';
+    this.retryAfterSeconds = retryAfterSeconds || null;
+  }
+}
+
+class ServiceUnavailableError extends SynapTransientError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'ServiceUnavailableError';
+  }
+}
+
+class AgentUnavailableError extends SynapTransientError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'AgentUnavailableError';
+  }
+}
+
+class InvalidInputError extends SynapPermanentError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'InvalidInputError';
+  }
+}
+
+class InvalidInstanceIdError extends InvalidInputError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'InvalidInstanceIdError';
+  }
+}
+
+class InvalidConversationIdError extends InvalidInputError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'InvalidConversationIdError';
+  }
+}
+
+class AuthenticationError extends SynapPermanentError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'AuthenticationError';
+  }
+}
+
+class CertificateExpiredError extends AuthenticationError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'CertificateExpiredError';
+  }
+}
+
+class CertificateRenewalError extends AuthenticationError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'CertificateRenewalError';
+  }
+}
+
+class BootstrapKeyInvalidError extends AuthenticationError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'BootstrapKeyInvalidError';
+  }
+}
+
+class BootstrapError extends SynapPermanentError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'BootstrapError';
+  }
+}
+
+class ContextNotFoundError extends SynapPermanentError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'ContextNotFoundError';
+  }
+}
+
+class SessionExpiredError extends SynapPermanentError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'SessionExpiredError';
+  }
+}
+
+class ListeningAlreadyActiveError extends SynapPermanentError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'ListeningAlreadyActiveError';
+  }
+}
+
+class ListeningNotActiveError extends SynapPermanentError {
+  constructor(message, correlationId) {
+    super(message, correlationId);
+    this.name = 'ListeningNotActiveError';
+  }
+}
+
+const ERROR_MAP = {
+  SynapError,
+  SynapTransientError,
+  SynapPermanentError,
+  NetworkTimeoutError,
+  RateLimitError,
+  ServiceUnavailableError,
+  AgentUnavailableError,
+  InvalidInputError,
+  InvalidInstanceIdError,
+  InvalidConversationIdError,
+  AuthenticationError,
+  CertificateExpiredError,
+  CertificateRenewalError,
+  BootstrapKeyInvalidError,
+  BootstrapError,
+  ContextNotFoundError,
+  SessionExpiredError,
+  ListeningAlreadyActiveError,
+  ListeningNotActiveError,
+};
+
+function createSynapError(message, errorType) {
+  const ErrorClass = ERROR_MAP[errorType];
+  if (ErrorClass) return new ErrorClass(message);
+  return new SynapError(message);
+}
+
+module.exports = {
+  SynapError,
+  SynapTransientError,
+  SynapPermanentError,
+  NetworkTimeoutError,
+  RateLimitError,
+  ServiceUnavailableError,
+  AgentUnavailableError,
+  InvalidInputError,
+  InvalidInstanceIdError,
+  InvalidConversationIdError,
+  AuthenticationError,
+  CertificateExpiredError,
+  CertificateRenewalError,
+  BootstrapKeyInvalidError,
+  BootstrapError,
+  ContextNotFoundError,
+  SessionExpiredError,
+  ListeningAlreadyActiveError,
+  ListeningNotActiveError,
+  createSynapError,
+};

package/src/index.js

@@ -1,6 +1,7 @@
 const { SynapClient } = require('./synap-client');
 const { setupPythonRuntime, resolveInstanceId } = require('./runtime');
 const { setupTypeScriptExtension } = require('./setup-typescript');
+const errors = require('./errors');
 
 module.exports = {
   SynapClient,
@@ -8,4 +9,5 @@ module.exports = {
   setupPythonRuntime,
   setupTypeScriptExtension,
   resolveInstanceId,
+  ...errors,
 };

package/src/setup-typescript.js

@@ -64,6 +64,10 @@ function getWrapperTemplate() {
   type AddMemoryInput,
   type SearchMemoryInput,
   type GetMemoriesInput,
+  type FetchUserContextInput,
+  type FetchCustomerContextInput,
+  type FetchClientContextInput,
+  type GetContextForPromptInput,
   type DeleteMemoryInput,
 } from '@maximem/synap-js-sdk';
 
@@ -90,6 +94,22 @@ export class SynapTsClient {
     return this.client.getMemories(input);
   }
 
+  fetchUserContext(input: FetchUserContextInput) {
+    return this.client.fetchUserContext(input);
+  }
+
+  fetchCustomerContext(input: FetchCustomerContextInput) {
+    return this.client.fetchCustomerContext(input);
+  }
+
+  fetchClientContext(input?: FetchClientContextInput) {
+    return this.client.fetchClientContext(input);
+  }
+
+  getContextForPrompt(input: GetContextForPromptInput) {
+    return this.client.getContextForPrompt(input);
+  }
+
   deleteMemory(input: DeleteMemoryInput) {
     return this.client.deleteMemory(input);
   }

package/src/synap-client.js

@@ -1,5 +1,200 @@
 const { BridgeManager } = require('./bridge-manager');
 
+function pickDefined(...values) {
+  for (const value of values) {
+    if (value !== undefined) return value;
+  }
+  return undefined;
+}
+
+function normalizeTemporalFields(item = {}) {
+  return {
+    eventDate: pickDefined(item.eventDate, item.event_date, null),
+    validUntil: pickDefined(item.validUntil, item.valid_until, null),
+    temporalCategory: pickDefined(item.temporalCategory, item.temporal_category, null),
+    temporalConfidence: pickDefined(item.temporalConfidence, item.temporal_confidence, 0),
+  };
+}
+
+function normalizeMemoryItem(item = {}) {
+  return {
+    id: item.id || '',
+    memory: pickDefined(item.memory, item.content, ''),
+    score: item.score,
+    source: item.source,
+    metadata: item.metadata || {},
+    contextType: pickDefined(item.contextType, item.context_type),
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeContextMetadata(metadata = {}) {
+  return {
+    correlationId: pickDefined(metadata.correlationId, metadata.correlation_id, ''),
+    ttlSeconds: pickDefined(metadata.ttlSeconds, metadata.ttl_seconds, 0),
+    source: metadata.source || 'unknown',
+    retrievedAt: pickDefined(metadata.retrievedAt, metadata.retrieved_at, null),
+    compactionApplied: pickDefined(metadata.compactionApplied, metadata.compaction_applied, null),
+  };
+}
+
+function normalizeConversationContext(value) {
+  if (!value) return null;
+  return {
+    summary: value.summary || null,
+    currentState: pickDefined(value.currentState, value.current_state, {}),
+    keyExtractions: pickDefined(value.keyExtractions, value.key_extractions, {}),
+    recentTurns: pickDefined(value.recentTurns, value.recent_turns, []),
+    compactionId: pickDefined(value.compactionId, value.compaction_id, null),
+    compactedAt: pickDefined(value.compactedAt, value.compacted_at, null),
+    conversationId: pickDefined(value.conversationId, value.conversation_id, null),
+  };
+}
+
+function normalizeFact(item = {}) {
+  return {
+    id: item.id || '',
+    content: item.content || '',
+    confidence: pickDefined(item.confidence, 0),
+    source: item.source || '',
+    extractedAt: pickDefined(item.extractedAt, item.extracted_at, null),
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizePreference(item = {}) {
+  return {
+    id: item.id || '',
+    category: item.category || '',
+    content: item.content || '',
+    strength: pickDefined(item.strength, item.confidence, 0),
+    source: item.source || '',
+    extractedAt: pickDefined(item.extractedAt, item.extracted_at, null),
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeEpisode(item = {}) {
+  return {
+    id: item.id || '',
+    summary: pickDefined(item.summary, item.content, ''),
+    occurredAt: pickDefined(item.occurredAt, item.occurred_at, null),
+    significance: pickDefined(item.significance, item.confidence, 0),
+    participants: item.participants || [],
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeEmotion(item = {}) {
+  return {
+    id: item.id || '',
+    emotionType: pickDefined(item.emotionType, item.emotion_type, ''),
+    intensity: pickDefined(item.intensity, item.confidence, 0),
+    detectedAt: pickDefined(item.detectedAt, item.detected_at, null),
+    context: item.context || '',
+    metadata: item.metadata || {},
+    ...normalizeTemporalFields(item),
+  };
+}
+
+function normalizeTemporalEvent(item = {}) {
+  return {
+    id: item.id || '',
+    content: item.content || '',
+    eventDate: pickDefined(item.eventDate, item.event_date, null),
+    validUntil: pickDefined(item.validUntil, item.valid_until, null),
+    temporalCategory: pickDefined(item.temporalCategory, item.temporal_category, ''),
+    temporalConfidence: pickDefined(item.temporalConfidence, item.temporal_confidence, 0),
+    confidence: pickDefined(item.confidence, 0),
+    source: item.source || '',
+    extractedAt: pickDefined(item.extractedAt, item.extracted_at, null),
+    metadata: item.metadata || {},
+  };
+}
+
+function normalizeContextResponse(result = {}) {
+  const context = result.context || result;
+  return {
+    facts: (context.facts || []).map(normalizeFact),
+    preferences: (context.preferences || []).map(normalizePreference),
+    episodes: (context.episodes || []).map(normalizeEpisode),
+    emotions: (context.emotions || []).map(normalizeEmotion),
+    temporalEvents: (pickDefined(context.temporalEvents, context.temporal_events, []) || []).map(normalizeTemporalEvent),
+    conversationContext: normalizeConversationContext(
+      pickDefined(context.conversationContext, context.conversation_context, null)
+    ),
+    metadata: normalizeContextMetadata(context.metadata || {}),
+    rawResponse: pickDefined(context.rawResponse, context.raw_response, {}),
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeRecentMessage(item = {}) {
+  return {
+    role: item.role || 'user',
+    content: item.content || '',
+    timestamp: item.timestamp || null,
+    messageId: pickDefined(item.messageId, item.message_id, ''),
+  };
+}
+
+function normalizeContextForPromptResult(result = {}) {
+  const payload = pickDefined(result.contextForPrompt, result.context_for_prompt, result);
+  return {
+    formattedContext: pickDefined(payload.formattedContext, payload.formatted_context, null),
+    available: !!payload.available,
+    isStale: !!pickDefined(payload.isStale, payload.is_stale, false),
+    compressionRatio: pickDefined(payload.compressionRatio, payload.compression_ratio, null),
+    validationScore: pickDefined(payload.validationScore, payload.validation_score, null),
+    compactionAgeSeconds: pickDefined(payload.compactionAgeSeconds, payload.compaction_age_seconds, null),
+    qualityWarning: !!pickDefined(payload.qualityWarning, payload.quality_warning, false),
+    recentMessages: (pickDefined(payload.recentMessages, payload.recent_messages, []) || []).map(normalizeRecentMessage),
+    recentMessageCount: pickDefined(payload.recentMessageCount, payload.recent_message_count, 0),
+    compactedMessageCount: pickDefined(payload.compactedMessageCount, payload.compacted_message_count, 0),
+    totalMessageCount: pickDefined(payload.totalMessageCount, payload.total_message_count, 0),
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeSearchMemoryResult(result = {}) {
+  return {
+    success: !!result.success,
+    latencyMs: result.latencyMs || 0,
+    results: (result.results || []).map(normalizeMemoryItem),
+    resultsCount: pickDefined(result.resultsCount, result.results?.length, 0),
+    rawResponse: result.rawResponse || {},
+    source: result.source,
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeGetMemoriesResult(result = {}) {
+  const memories = (result.memories || []).map(normalizeMemoryItem);
+  return {
+    success: !!result.success,
+    latencyMs: result.latencyMs || 0,
+    memories,
+    totalCount: pickDefined(result.totalCount, result.memoriesCount, memories.length, 0),
+    rawResponse: pickDefined(result.rawResponse, null),
+    source: result.source,
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
+function normalizeDeleteMemoryResult(result = {}) {
+  return {
+    success: !!result.success,
+    latencyMs: result.latencyMs || 0,
+    deletedCount: pickDefined(result.deletedCount, result.rawResponse?.deleted, 0),
+    rawResponse: pickDefined(result.rawResponse, null),
+    note: result.note,
+    bridgeTiming: result.bridgeTiming,
+  };
+}
+
 class SynapClient {
   constructor(options = {}) {
     this.bridge = new BridgeManager(options);
@@ -14,42 +209,122 @@ class SynapClient {
     await this.bridge.ensureStarted();
   }
 
-  async addMemory({ userId, messages, mode }) {
+  async addMemory({
+    userId,
+    customerId,
+    conversationId,
+    sessionId,
+    messages,
+    mode,
+    documentType,
+    documentId,
+    documentCreatedAt,
+    metadata,
+  }) {
     this.#assert(userId, 'userId is required');
+    this.#assert(customerId, 'customerId is required');
     this.#assert(Array.isArray(messages), 'messages must be an array');
 
     const params = { user_id: userId, messages };
+    params.customer_id = customerId;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (sessionId !== undefined) params.session_id = sessionId;
     if (mode !== undefined) params.mode = mode;
+    if (documentType !== undefined) params.document_type = documentType;
+    if (documentId !== undefined) params.document_id = documentId;
+    if (documentCreatedAt !== undefined) params.document_created_at = documentCreatedAt;
+    if (metadata !== undefined) params.metadata = metadata;
 
     return this.bridge.call('add_memory', params, this.options.ingestTimeoutMs);
   }
 
-  async searchMemory({ userId, query, maxResults = 10, mode }) {
+  async searchMemory({ userId, customerId, query, maxResults = 10, mode, conversationId, types }) {
     this.#assert(userId, 'userId is required');
     this.#assert(query, 'query is required');
+    this.#assertArray(types, 'types must be an array when provided');
 
     const params = { user_id: userId, query, max_results: maxResults };
+    if (customerId !== undefined) params.customer_id = customerId;
     if (mode !== undefined) params.mode = mode;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (types !== undefined) params.types = types;
 
-    return this.bridge.call('search_memory', params);
+    return normalizeSearchMemoryResult(await this.bridge.call('search_memory', params));
   }
 
-  async getMemories({ userId, mode }) {
+  async getMemories({ userId, customerId, mode, conversationId, maxResults, types }) {
     this.#assert(userId, 'userId is required');
+    this.#assertArray(types, 'types must be an array when provided');
 
     const params = { user_id: userId };
+    if (customerId !== undefined) params.customer_id = customerId;
     if (mode !== undefined) params.mode = mode;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (maxResults !== undefined) params.max_results = maxResults;
+    if (types !== undefined) params.types = types;
 
-    return this.bridge.call('get_memories', params);
+    return normalizeGetMemoriesResult(await this.bridge.call('get_memories', params));
   }
 
-  async deleteMemory({ userId, memoryId = null }) {
+  async fetchUserContext({ userId, customerId, conversationId, searchQuery, maxResults = 10, types, mode }) {
     this.#assert(userId, 'userId is required');
+    this.#assertArray(searchQuery, 'searchQuery must be an array when provided');
+    this.#assertArray(types, 'types must be an array when provided');
 
-    return this.bridge.call('delete_memory', {
-      user_id: userId,
-      memory_id: memoryId,
-    });
+    const params = { user_id: userId, max_results: maxResults };
+    if (customerId !== undefined) params.customer_id = customerId;
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (searchQuery !== undefined) params.search_query = searchQuery;
+    if (types !== undefined) params.types = types;
+    if (mode !== undefined) params.mode = mode;
+
+    return normalizeContextResponse(await this.bridge.call('fetch_user_context', params));
+  }
+
+  async fetchCustomerContext({ customerId, conversationId, searchQuery, maxResults = 10, types, mode }) {
+    this.#assert(customerId, 'customerId is required');
+    this.#assertArray(searchQuery, 'searchQuery must be an array when provided');
+    this.#assertArray(types, 'types must be an array when provided');
+
+    const params = { customer_id: customerId, max_results: maxResults };
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (searchQuery !== undefined) params.search_query = searchQuery;
+    if (types !== undefined) params.types = types;
+    if (mode !== undefined) params.mode = mode;
+
+    return normalizeContextResponse(await this.bridge.call('fetch_customer_context', params));
+  }
+
+  async fetchClientContext({ conversationId, searchQuery, maxResults = 10, types, mode } = {}) {
+    this.#assertArray(searchQuery, 'searchQuery must be an array when provided');
+    this.#assertArray(types, 'types must be an array when provided');
+
+    const params = { max_results: maxResults };
+    if (conversationId !== undefined) params.conversation_id = conversationId;
+    if (searchQuery !== undefined) params.search_query = searchQuery;
+    if (types !== undefined) params.types = types;
+    if (mode !== undefined) params.mode = mode;
+
+    return normalizeContextResponse(await this.bridge.call('fetch_client_context', params));
+  }
+
+  async getContextForPrompt({ conversationId, style } = {}) {
+    this.#assert(conversationId, 'conversationId is required');
+
+    const params = { conversation_id: conversationId };
+    if (style !== undefined) params.style = style;
+
+    return normalizeContextForPromptResult(await this.bridge.call('get_context_for_prompt', params));
+  }
+
+  async deleteMemory({ userId, customerId, memoryId = null }) {
+    this.#assert(userId, 'userId is required');
+    if (memoryId == null) this.#assert(customerId, 'customerId is required when memoryId is not provided');
+
+    const params = { user_id: userId, memory_id: memoryId };
+    if (customerId !== undefined) params.customer_id = customerId;
+
+    return normalizeDeleteMemoryResult(await this.bridge.call('delete_memory', params));
   }
 
   async shutdown() {
@@ -60,6 +335,10 @@ class SynapClient {
     if (!value) throw new Error(message);
   }
 
+  #assertArray(value, message) {
+    if (value !== undefined && !Array.isArray(value)) throw new Error(message);
+  }
+
   #registerShutdownHooks() {
     const close = async () => {
       try {