@maximem/synap-js-sdk 0.2.3 → 0.3.0

package/README.md

@@ -37,14 +37,13 @@ Windows:
 $env:USERPROFILE\.synap-js-sdk\.venv\Scripts\python.exe -c "import maximem_synap; print(maximem_synap.__version__)"
 ```
 
-## Required Environment Variables
+## Required Environment Variable
 
 - `SYNAP_API_KEY` (from the Synap dashboard — Instances → Generate API Key)
-- `SYNAP_INSTANCE_ID`
-- `SYNAP_BASE_URL`
-- `SYNAP_GRPC_HOST`
-- `SYNAP_GRPC_PORT`
-- `SYNAP_GRPC_TLS`
+
+The SDK uses the default Synap cloud endpoints automatically. `SYNAP_BASE_URL`,
+`SYNAP_GRPC_HOST`, `SYNAP_GRPC_PORT`, and `SYNAP_GRPC_TLS` are only needed for
+advanced overrides such as local development or custom environments.
 
 ## Quick Start (JavaScript)
 
@@ -52,12 +51,7 @@ $env:USERPROFILE\.synap-js-sdk\.venv\Scripts\python.exe -c "import maximem_synap
 const { createClient } = require('@maximem/synap-js-sdk');
 
 const synap = createClient({
-  instanceId: process.env.SYNAP_INSTANCE_ID,
   apiKey: process.env.SYNAP_API_KEY,
-  baseUrl: process.env.SYNAP_BASE_URL,
-  grpcHost: process.env.SYNAP_GRPC_HOST,
-  grpcPort: Number(process.env.SYNAP_GRPC_PORT || 50051),
-  grpcUseTls: process.env.SYNAP_GRPC_TLS === 'true',
 });
 
 async function run() {

package/bridge/synap_bridge.py

@@ -5,9 +5,9 @@ Protocol:
   stdin  -> {"id": 1, "method": "init", "params": {...}}\n
   stdout <- {"id": 1, "result": {...}, "error": null}\n
 Methods:
-  init, add_memory, search_memory, get_memories, fetch_user_context,
-  fetch_customer_context, fetch_client_context, get_context_for_prompt,
-  delete_memory, shutdown
+  init, add_memory, create_memory, record_message, search_memory, get_memories,
+  fetch_user_context, fetch_customer_context, fetch_client_context,
+  get_context_for_prompt, delete_memory, shutdown
 """
 
 import asyncio
@@ -637,9 +637,69 @@ async def handle_shutdown(_params: dict) -> dict:
     }
 
 
+async def handle_record_message(params: dict) -> dict:
+    """Record a single conversation turn (registers the conversation_id).
+
+    Mirrors sdk.conversation.record_message(...) so the JS client can expose
+    the same namespaced surface the integration packages duck-type against.
+    """
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+    step = time.perf_counter()
+    result = await sdk.conversation.record_message(
+        conversation_id=params["conversation_id"],
+        role=params["role"],
+        content=params["content"],
+        user_id=params["user_id"],
+        customer_id=params["customer_id"],
+        session_id=params.get("session_id"),
+        metadata=params.get("metadata"),
+    )
+    append_step(timings, "record_message", step)
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "result": result,
+        "bridgeTiming": {"python_total_ms": ms_since(handler_start), "steps": timings},
+    }
+
+
+async def handle_create_memory(params: dict) -> dict:
+    """Create a durable memory from a single document string.
+
+    Mirrors sdk.memories.create(document=...). Distinct from add_memory,
+    which builds a transcript from a messages array.
+    """
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+    create_kwargs: dict = {"document": params["document"]}
+    for key in ("user_id", "customer_id", "document_type", "document_id",
+                "document_created_at", "mode", "metadata"):
+        if params.get(key) is not None:
+            create_kwargs[key] = params[key]
+    step = time.perf_counter()
+    result = await sdk.memories.create(**create_kwargs)
+    append_step(timings, "memories_create", step)
+    status = result.status.value if hasattr(result.status, "value") else result.status
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "result": {
+            "ingestion_id": str(result.ingestion_id),
+            "document_id": result.document_id,
+            "status": status,
+        },
+        "bridgeTiming": {"python_total_ms": ms_since(handler_start), "steps": timings},
+    }
+
+
 HANDLERS = {
     "init": handle_init,
     "add_memory": handle_add_memory,
+    "create_memory": handle_create_memory,
+    "record_message": handle_record_message,
     "search_memory": handle_search_memory,
     "get_memories": handle_get_memories,
     "fetch_user_context": handle_fetch_user_context,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maximem/synap-js-sdk",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "description": "JavaScript wrapper around the Synap Python SDK",
   "main": "src/index.js",
   "types": "types/index.d.ts",
@@ -19,7 +19,11 @@
   "scripts": {
     "setup": "node bin/synap-js-sdk.js setup",
     "setup:ts": "node bin/synap-js-sdk.js setup-ts",
-    "check": "node -e \"const sdk=require('./src'); console.log(Object.keys(sdk));\""
+    "check": "node -e \"const sdk=require('./src'); console.log(Object.keys(sdk));\"",
+    "test": "vitest run"
+  },
+  "devDependencies": {
+    "vitest": "^2.1.9"
   },
   "engines": {
     "node": ">=18"

package/src/errors.js

@@ -79,6 +79,21 @@ class AuthenticationError extends SynapPermanentError {
   }
 }
 
+class InsufficientCreditsError extends SynapPermanentError {
+  constructor(message, details, correlationId) {
+    super(message, correlationId);
+    this.name = 'InsufficientCreditsError';
+    // Structured details from the server's 402 response body:
+    //   { balance_credits, minimum_required_credits, recovery_url, redeem_url }
+    this.balanceCredits = details && details.balance_credits != null
+      ? Number(details.balance_credits) : null;
+    this.minimumRequiredCredits = details && details.minimum_required_credits != null
+      ? Number(details.minimum_required_credits) : null;
+    this.recoveryUrl = details && details.recovery_url ? details.recovery_url : null;
+    this.redeemUrl = details && details.redeem_url ? details.redeem_url : null;
+  }
+}
+
 class ContextNotFoundError extends SynapPermanentError {
   constructor(message, correlationId) {
     super(message, correlationId);
@@ -119,6 +134,7 @@ const ERROR_MAP = {
   InvalidInstanceIdError,
   InvalidConversationIdError,
   AuthenticationError,
+  InsufficientCreditsError,
   ContextNotFoundError,
   SessionExpiredError,
   ListeningAlreadyActiveError,
@@ -143,6 +159,7 @@ module.exports = {
   InvalidInstanceIdError,
   InvalidConversationIdError,
   AuthenticationError,
+  InsufficientCreditsError,
   ContextNotFoundError,
   SessionExpiredError,
   ListeningAlreadyActiveError,

package/src/synap-client.js

@@ -203,6 +203,7 @@ class SynapClient {
     };
 
     this.#registerShutdownHooks();
+    this.#installNamespacedApi();
   }
 
   async init() {
@@ -358,6 +359,106 @@ class SynapClient {
       process.exit(0);
     });
   }
+
+  #installNamespacedApi() {
+    const buildParams = (args = {}) => {
+      const params = {};
+      const conv = pickDefined(args.conversation_id, args.conversationId);
+      const sq = pickDefined(args.search_query, args.searchQuery);
+      const mr = pickDefined(args.max_results, args.maxResults);
+      if (conv !== undefined && conv !== null) params.conversation_id = conv;
+      if (sq !== undefined && sq !== null) params.search_query = sq;
+      if (mr !== undefined) params.max_results = mr;
+      if (args.types !== undefined) params.types = args.types;
+      if (args.mode !== undefined) params.mode = args.mode;
+      return params;
+    };
+    const fetch = async (args = {}) => {
+      const userId = pickDefined(args.user_id, args.userId);
+      const customerId = pickDefined(args.customer_id, args.customerId);
+      const params = buildParams(args);
+      let command;
+      if (userId !== undefined && userId !== null) {
+        command = 'fetch_user_context';
+        params.user_id = userId;
+        if (customerId !== undefined && customerId !== null) params.customer_id = customerId;
+      } else if (customerId !== undefined && customerId !== null) {
+        command = 'fetch_customer_context';
+        params.customer_id = customerId;
+      } else {
+        command = 'fetch_client_context';
+      }
+      const result = await this.bridge.call(command, params);
+      return result.context || {};
+    };
+    const fetchScope = (command, idKeys) => async (args = {}) => {
+      const params = buildParams(args);
+      if (idKeys.includes('user_id')) {
+        const userId = pickDefined(args.user_id, args.userId);
+        if (userId !== undefined && userId !== null) params.user_id = userId;
+      }
+      if (idKeys.includes('customer_id')) {
+        const customerId = pickDefined(args.customer_id, args.customerId);
+        if (customerId !== undefined && customerId !== null) params.customer_id = customerId;
+      }
+      const result = await this.bridge.call(command, params);
+      return result.context || {};
+    };
+    this.fetch = fetch;
+    this.conversation = {
+      record_message: async (args = {}) => {
+        const conversationId = pickDefined(args.conversation_id, args.conversationId);
+        const userId = pickDefined(args.user_id, args.userId);
+        const customerId = pickDefined(args.customer_id, args.customerId);
+        this.#assert(conversationId, 'conversation_id is required');
+        this.#assert(userId, 'user_id is required');
+        this.#assert(customerId, 'customer_id is required');
+        const params = {
+          conversation_id: conversationId, role: args.role, content: args.content,
+          user_id: userId, customer_id: customerId,
+        };
+        const sessionId = pickDefined(args.session_id, args.sessionId);
+        if (sessionId !== undefined) params.session_id = sessionId;
+        if (args.metadata !== undefined) params.metadata = args.metadata;
+        const result = await this.bridge.call('record_message', params);
+        return pickDefined(result.result, result);
+      },
+      context: {
+        get_context_for_prompt: async (args = {}) => {
+          const conversationId = pickDefined(args.conversation_id, args.conversationId);
+          this.#assert(conversationId, 'conversation_id is required');
+          const params = { conversation_id: conversationId };
+          if (args.style !== undefined) params.style = args.style;
+          const result = await this.bridge.call('get_context_for_prompt', params);
+          return pickDefined(result.context_for_prompt, result.contextForPrompt, {});
+        },
+        fetch,
+      },
+    };
+    this.memories = {
+      create: async (args = {}) => {
+        this.#assert(args.document, 'document is required');
+        const params = { document: args.document };
+        const userId = pickDefined(args.user_id, args.userId);
+        const customerId = pickDefined(args.customer_id, args.customerId);
+        const documentType = pickDefined(args.document_type, args.documentType);
+        const documentId = pickDefined(args.document_id, args.documentId);
+        const documentCreatedAt = pickDefined(args.document_created_at, args.documentCreatedAt);
+        if (userId !== undefined) params.user_id = userId;
+        if (customerId !== undefined) params.customer_id = customerId;
+        if (documentType !== undefined) params.document_type = documentType;
+        if (documentId !== undefined) params.document_id = documentId;
+        if (documentCreatedAt !== undefined) params.document_created_at = documentCreatedAt;
+        if (args.mode !== undefined) params.mode = args.mode;
+        if (args.metadata !== undefined) params.metadata = args.metadata;
+        const result = await this.bridge.call('create_memory', params, this.options.ingestTimeoutMs);
+        return pickDefined(result.result, result);
+      },
+    };
+    this.user = { context: { fetch: fetchScope('fetch_user_context', ['user_id', 'customer_id']) } };
+    this.customer = { context: { fetch: fetchScope('fetch_customer_context', ['customer_id']) } };
+    this.client = { context: { fetch: fetchScope('fetch_client_context', []) } };
+  }
 }
 
 module.exports = { SynapClient };

package/types/index.d.ts

@@ -29,7 +29,6 @@ export interface BridgeLogHandler {
 }
 
 export interface SynapClientOptions {
-  instanceId?: string;
   apiKey?: string;
   baseUrl?: string;
   grpcHost?: string;
@@ -297,6 +296,75 @@ export interface DeleteMemoryResult {
   bridgeTiming?: BridgeTiming;
 }
 
+export interface SynapNamespacedFetchInput {
+  userId?: string | null;
+  user_id?: string | null;
+  customerId?: string | null;
+  customer_id?: string | null;
+  conversationId?: string | null;
+  conversation_id?: string | null;
+  searchQuery?: string[] | null;
+  search_query?: string[] | null;
+  maxResults?: number;
+  max_results?: number;
+  types?: string[];
+  mode?: string;
+}
+
+export interface SynapRecordMessageInput {
+  conversationId?: string | null;
+  conversation_id?: string | null;
+  role: string;
+  content: string;
+  userId?: string | null;
+  user_id?: string | null;
+  customerId?: string | null;
+  customer_id?: string | null;
+  sessionId?: string | null;
+  session_id?: string | null;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SynapCreateMemoryInput {
+  document: string;
+  userId?: string | null;
+  user_id?: string | null;
+  customerId?: string | null;
+  customer_id?: string | null;
+  documentType?: string | null;
+  document_type?: string | null;
+  documentId?: string | null;
+  document_id?: string | null;
+  documentCreatedAt?: string | null;
+  document_created_at?: string | null;
+  mode?: string | null;
+  metadata?: Record<string, unknown>;
+}
+
+export interface SynapGetContextForPromptInput {
+  conversationId?: string;
+  conversation_id?: string;
+  style?: string;
+}
+
+export interface SynapScopeContextApi {
+  context: {
+    fetch(input?: SynapNamespacedFetchInput): Promise<any>;
+  };
+}
+
+export interface SynapConversationApi {
+  record_message(input: SynapRecordMessageInput): Promise<any>;
+  context: {
+    get_context_for_prompt(input: SynapGetContextForPromptInput): Promise<any>;
+    fetch(input?: SynapNamespacedFetchInput): Promise<any>;
+  };
+}
+
+export interface SynapMemoriesApi {
+  create(input: SynapCreateMemoryInput): Promise<any>;
+}
+
 export class SynapClient {
   constructor(options?: SynapClientOptions);
   init(): Promise<void>;
@@ -309,6 +377,12 @@ export class SynapClient {
   getContextForPrompt(input: GetContextForPromptInput): Promise<ContextForPromptResult>;
   deleteMemory(input: DeleteMemoryInput): Promise<DeleteMemoryResult>;
   shutdown(): Promise<void>;
+  fetch(input?: SynapNamespacedFetchInput): Promise<any>;
+  readonly conversation: SynapConversationApi;
+  readonly memories: SynapMemoriesApi;
+  readonly user: SynapScopeContextApi;
+  readonly customer: SynapScopeContextApi;
+  readonly client: SynapScopeContextApi;
 }
 
 export interface SetupPythonRuntimeOptions {
@@ -370,6 +444,22 @@ export class InvalidInputError extends SynapPermanentError {}
 export class InvalidInstanceIdError extends InvalidInputError {}
 export class InvalidConversationIdError extends InvalidInputError {}
 export class AuthenticationError extends SynapPermanentError {}
+export class InsufficientCreditsError extends SynapPermanentError {
+  balanceCredits: number | null;
+  minimumRequiredCredits: number | null;
+  recoveryUrl: string | null;
+  redeemUrl: string | null;
+  constructor(
+    message: string,
+    details?: {
+      balance_credits?: number | null;
+      minimum_required_credits?: number | null;
+      recovery_url?: string | null;
+      redeem_url?: string | null;
+    },
+    correlationId?: string,
+  );
+}
 export class ContextNotFoundError extends SynapPermanentError {}
 export class SessionExpiredError extends SynapPermanentError {}
 export class ListeningAlreadyActiveError extends SynapPermanentError {}