@maximem/synap-js-sdk 0.1.4 → 0.2.1

package/README.md

@@ -18,10 +18,10 @@ npm install @maximem/synap-js-sdk
 Install the Python runtime used by the wrapper:
 
 ```bash
-npx synap-js-sdk setup --sdk-version 0.1.1
+npx synap-js-sdk setup --sdk-version 0.2.0
 ```
 
-If you want the latest Python SDK version, omit `--sdk-version`.
+If you want the latest Python SDK version, omit `--sdk-version` and pass `--upgrade`.
 
 ## Verify Runtime
 
@@ -65,16 +65,27 @@ async function run() {
 
   await synap.addMemory({
     userId: 'user-123',
+    customerId: 'customer-456',
+    conversationId: 'conv-123',
     messages: [{ role: 'user', content: 'My name is Alex and I live in Austin.' }],
   });
 
-  const result = await synap.searchMemory({
+  const context = await synap.fetchUserContext({
     userId: 'user-123',
-    query: 'Where does the user live?',
+    customerId: 'customer-456',
+    conversationId: 'conv-123',
+    searchQuery: ['Where does the user live?'],
     maxResults: 10,
   });
 
-  console.log(result);
+  console.log(context.facts);
+
+  const promptContext = await synap.getContextForPrompt({
+    conversationId: 'conv-123',
+    style: 'structured',
+  });
+
+  console.log(promptContext.formattedContext);
   await synap.shutdown();
 }
 
@@ -97,9 +108,17 @@ This command can:
 ## Single-Flow Setup (JS + TS)
 
 ```bash
-npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version 0.1.1 && npx synap-js-sdk setup-ts
+npm install @maximem/synap-js-sdk && npx synap-js-sdk setup --sdk-version 0.2.0 && npx synap-js-sdk setup-ts
 ```
 
+## API Notes
+
+- `addMemory()` now requires `customerId` to match the Python SDK's explicit ingestion scope.
+- `fetchUserContext()`, `fetchCustomerContext()`, and `fetchClientContext()` expose the structured Python `ContextResponse` surface in JS/TS.
+- `getContextForPrompt()` exposes compacted context plus recent un-compacted messages.
+- `searchMemory()` and `getMemories()` remain convenience helpers built on top of user-scoped context fetches.
+- Temporal fields are exposed in JS/TS as `eventDate`, `validUntil`, `temporalCategory`, `temporalConfidence`, plus top-level `temporalEvents`.
+
 ## CLI Commands
 
 ```bash

package/bridge/synap_bridge.py

@@ -5,7 +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, delete_memory, shutdown
+  init, add_memory, search_memory, get_memories, fetch_user_context,
+  fetch_customer_context, fetch_client_context, get_context_for_prompt,
+  delete_memory, shutdown
 """
 
 import asyncio
@@ -51,6 +53,92 @@ def write_response(obj: dict) -> None:
     sys.stdout.flush()
 
 
+def tracking_key(user_id: str, customer_id: Optional[str]) -> str:
+    """Scope tracked memory IDs by both customer and user."""
+    return f"{customer_id or ''}::{user_id}"
+
+
+def serialize_context_response(context) -> dict:
+    """Serialize a Python ContextResponse for the JS bridge."""
+    payload = context.model_dump(mode="json")
+    payload["raw_response"] = context.raw if hasattr(context, "raw") else {}
+    return payload
+
+
+def serialize_context_for_prompt_response(response) -> dict:
+    """Serialize a Python ContextForPromptResponse for the JS bridge."""
+    return response.model_dump(mode="json")
+
+
+def flatten_context_items(context) -> List[dict]:
+    """Convert typed context collections into a flat memory list."""
+    items: List[dict] = []
+    for fact in context.facts:
+        items.append({
+            "id": fact.id,
+            "memory": fact.content,
+            "score": fact.confidence,
+            "source": fact.source,
+            "metadata": fact.metadata,
+            "context_type": "fact",
+            "event_date": str(fact.event_date) if getattr(fact, "event_date", None) else None,
+            "valid_until": str(fact.valid_until) if getattr(fact, "valid_until", None) else None,
+            "temporal_category": getattr(fact, "temporal_category", None),
+            "temporal_confidence": getattr(fact, "temporal_confidence", 0.0),
+        })
+    for preference in context.preferences:
+        items.append({
+            "id": preference.id,
+            "memory": preference.content,
+            "score": preference.strength,
+            "source": getattr(preference, "source", ""),
+            "metadata": preference.metadata,
+            "context_type": "preference",
+            "event_date": str(preference.event_date) if getattr(preference, "event_date", None) else None,
+            "valid_until": str(preference.valid_until) if getattr(preference, "valid_until", None) else None,
+            "temporal_category": getattr(preference, "temporal_category", None),
+            "temporal_confidence": getattr(preference, "temporal_confidence", 0.0),
+        })
+    for episode in context.episodes:
+        items.append({
+            "id": episode.id,
+            "memory": episode.summary,
+            "score": episode.significance,
+            "metadata": episode.metadata,
+            "context_type": "episode",
+            "event_date": str(episode.event_date) if getattr(episode, "event_date", None) else None,
+            "valid_until": str(episode.valid_until) if getattr(episode, "valid_until", None) else None,
+            "temporal_category": getattr(episode, "temporal_category", None),
+            "temporal_confidence": getattr(episode, "temporal_confidence", 0.0),
+        })
+    for emotion in context.emotions:
+        items.append({
+            "id": emotion.id,
+            "memory": emotion.context,
+            "score": emotion.intensity,
+            "metadata": emotion.metadata,
+            "context_type": "emotion",
+            "event_date": str(emotion.event_date) if getattr(emotion, "event_date", None) else None,
+            "valid_until": str(emotion.valid_until) if getattr(emotion, "valid_until", None) else None,
+            "temporal_category": getattr(emotion, "temporal_category", None),
+            "temporal_confidence": getattr(emotion, "temporal_confidence", 0.0),
+        })
+    for event in getattr(context, "temporal_events", []):
+        items.append({
+            "id": event.id,
+            "memory": event.content,
+            "score": event.temporal_confidence,
+            "source": event.source,
+            "metadata": event.metadata,
+            "context_type": "temporal_event",
+            "event_date": str(event.event_date) if event.event_date else None,
+            "valid_until": str(event.valid_until) if event.valid_until else None,
+            "temporal_category": event.temporal_category,
+            "temporal_confidence": event.temporal_confidence,
+        })
+    return items
+
+
 def messages_to_text(messages: List[dict]) -> str:
     lines: List[str] = []
     for message in messages:
@@ -147,7 +235,13 @@ async def handle_add_memory(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     messages = params["messages"]
+    conversation_id = params.get("conversation_id")
+    session_id = params.get("session_id")
+
+    if not customer_id:
+        raise ValueError("customer_id is required")
 
     step = time.perf_counter()
     transcript = messages_to_text(messages)
@@ -169,12 +263,26 @@ async def handle_add_memory(params: dict) -> dict:
 
     step = time.perf_counter()
     mode = params.get("mode", "long-range")
-    create_result = await sdk.memories.create(
-        document=transcript,
-        document_type="ai-chat-conversation",
-        user_id=user_id,
-        mode=mode,
-    )
+    document_type = params.get("document_type", "ai-chat-conversation")
+    document_id = params.get("document_id")
+    document_created_at = params.get("document_created_at")
+    metadata = params.get("metadata")
+
+    create_kwargs: dict = {
+        "document": transcript,
+        "document_type": document_type,
+        "user_id": user_id,
+        "customer_id": customer_id,
+        "mode": mode,
+    }
+    if document_id is not None:
+        create_kwargs["document_id"] = document_id
+    if document_created_at is not None:
+        create_kwargs["document_created_at"] = document_created_at
+    if metadata is not None:
+        create_kwargs["metadata"] = metadata
+
+    create_result = await sdk.memories.create(**create_kwargs)
     append_step(timings, "memories_create", step)
 
     ingestion_id = create_result.ingestion_id
@@ -186,10 +294,16 @@ async def handle_add_memory(params: dict) -> dict:
             if not content:
                 continue
             try:
+                role = message.get("role", "user")
                 await sdk.instance.send_message(
                     content=content,
-                    role=message.get("role", "user"),
+                    role=role,
+                    conversation_id=conversation_id,
                     user_id=user_id,
+                    customer_id=customer_id,
+                    session_id=session_id,
+                    event_type="assistant_message" if role == "assistant" else "user_message",
+                    metadata=message.get("metadata"),
                 )
             except Exception as exc:
                 logger.debug("gRPC send_message failed (non-fatal): %s", exc)
@@ -218,7 +332,7 @@ async def handle_add_memory(params: dict) -> dict:
 
     memory_ids = [str(memory_id) for memory_id in (final_status.memory_ids or [])]
     if memory_ids:
-        user_memory_ids.setdefault(user_id, []).extend(memory_ids)
+        user_memory_ids.setdefault(tracking_key(user_id, customer_id), []).extend(memory_ids)
 
     return {
         "success": final_status.status.value != "failed",
@@ -242,38 +356,29 @@ async def handle_search_memory(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     query = params["query"]
     max_results = params.get("max_results", 10)
     mode = params.get("mode", "fast")
+    conversation_id = params.get("conversation_id")
+    types = params.get("types", ["all"])
 
     start = time.perf_counter()
 
     step = time.perf_counter()
     context = await sdk.user.context.fetch(
         user_id=user_id,
+        customer_id=customer_id,
+        conversation_id=conversation_id,
         search_query=[query],
         max_results=max_results,
-        types=["all"],
+        types=types,
         mode=mode,
     )
     append_step(timings, "context_fetch", step)
 
     step = time.perf_counter()
-    results = []
-    for fact in context.facts:
-        results.append({"id": fact.id, "memory": fact.content, "score": fact.confidence})
-    for preference in context.preferences:
-        results.append(
-            {"id": preference.id, "memory": preference.content, "score": preference.strength}
-        )
-    for episode in context.episodes:
-        results.append(
-            {"id": episode.id, "memory": episode.summary, "score": episode.significance}
-        )
-    for emotion in context.emotions:
-        results.append(
-            {"id": emotion.id, "memory": emotion.context, "score": emotion.intensity}
-        )
+    results = flatten_context_items(context)
     append_step(timings, "map_context_results", step)
 
     return {
@@ -295,30 +400,28 @@ async def handle_get_memories(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     mode = params.get("mode", "fast")
+    conversation_id = params.get("conversation_id")
+    max_results = params.get("max_results", 100)
+    types = params.get("types", ["all"])
 
     start = time.perf_counter()
 
     step = time.perf_counter()
     context = await sdk.user.context.fetch(
         user_id=user_id,
+        customer_id=customer_id,
+        conversation_id=conversation_id,
         search_query=[],
-        max_results=100,
-        types=["all"],
+        max_results=max_results,
+        types=types,
         mode=mode,
     )
     append_step(timings, "context_fetch_all", step)
 
     step = time.perf_counter()
-    memories = []
-    for fact in context.facts:
-        memories.append({"id": fact.id, "memory": fact.content})
-    for preference in context.preferences:
-        memories.append({"id": preference.id, "memory": preference.content})
-    for episode in context.episodes:
-        memories.append({"id": episode.id, "memory": episode.summary})
-    for emotion in context.emotions:
-        memories.append({"id": emotion.id, "memory": emotion.context})
+    memories = flatten_context_items(context)
     append_step(timings, "map_memories", step)
 
     return {
@@ -326,7 +429,113 @@ async def handle_get_memories(params: dict) -> dict:
         "latencyMs": ms_since(start),
         "memories": memories,
         "memoriesCount": len(memories),
+        "totalCount": len(memories),
         "rawResponse": context.raw if hasattr(context, "raw") else {},
+        "source": context.metadata.source if context.metadata else "unknown",
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_fetch_user_context(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.user.context.fetch(
+        user_id=params["user_id"],
+        customer_id=params.get("customer_id"),
+        conversation_id=params.get("conversation_id"),
+        search_query=params.get("search_query"),
+        max_results=params.get("max_results", 10),
+        types=params.get("types"),
+        mode=params.get("mode", "fast"),
+    )
+    append_step(timings, "context_fetch", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context": serialize_context_response(context),
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_fetch_customer_context(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.customer.context.fetch(
+        customer_id=params["customer_id"],
+        conversation_id=params.get("conversation_id"),
+        search_query=params.get("search_query"),
+        max_results=params.get("max_results", 10),
+        types=params.get("types"),
+        mode=params.get("mode", "fast"),
+    )
+    append_step(timings, "context_fetch", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context": serialize_context_response(context),
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_fetch_client_context(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    context = await sdk.client.context.fetch(
+        conversation_id=params.get("conversation_id"),
+        search_query=params.get("search_query"),
+        max_results=params.get("max_results", 10),
+        types=params.get("types"),
+        mode=params.get("mode", "fast"),
+    )
+    append_step(timings, "context_fetch", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context": serialize_context_response(context),
+        "bridgeTiming": {
+            "python_total_ms": ms_since(handler_start),
+            "steps": timings,
+        },
+    }
+
+
+async def handle_get_context_for_prompt(params: dict) -> dict:
+    handler_start = time.perf_counter()
+    timings: List[dict] = []
+    start = time.perf_counter()
+
+    step = time.perf_counter()
+    response = await sdk.conversation.get_context_for_prompt(
+        conversation_id=params["conversation_id"],
+        style=params.get("style", "structured"),
+    )
+    append_step(timings, "get_context_for_prompt", step)
+
+    return {
+        "success": True,
+        "latencyMs": ms_since(start),
+        "context_for_prompt": serialize_context_for_prompt_response(response),
         "bridgeTiming": {
             "python_total_ms": ms_since(handler_start),
             "steps": timings,
@@ -339,6 +548,7 @@ async def handle_delete_memory(params: dict) -> dict:
     timings: List[dict] = []
 
     user_id = params["user_id"]
+    customer_id = params.get("customer_id")
     memory_id = params.get("memory_id")
 
     start = time.perf_counter()
@@ -350,6 +560,7 @@ async def handle_delete_memory(params: dict) -> dict:
         return {
             "success": True,
             "latencyMs": ms_since(start),
+            "deletedCount": 1,
             "rawResponse": {"deleted": 1},
             "bridgeTiming": {
                 "python_total_ms": ms_since(handler_start),
@@ -357,11 +568,15 @@ async def handle_delete_memory(params: dict) -> dict:
             },
         }
 
-    tracked_ids = user_memory_ids.get(user_id, [])
+    if not customer_id:
+        raise ValueError("customer_id is required when memory_id is not provided")
+
+    tracked_ids = user_memory_ids.get(tracking_key(user_id, customer_id), [])
     if not tracked_ids:
         return {
             "success": True,
             "latencyMs": 0,
+            "deletedCount": 0,
             "rawResponse": None,
             "note": "No tracked memory IDs for this user",
             "bridgeTiming": {
@@ -380,7 +595,7 @@ async def handle_delete_memory(params: dict) -> dict:
             last_error = str(exc)
     append_step(timings, "delete_tracked_memories", step)
 
-    user_memory_ids.pop(user_id, None)
+    user_memory_ids.pop(tracking_key(user_id, customer_id), None)
 
     if last_error:
         return {
@@ -396,6 +611,7 @@ async def handle_delete_memory(params: dict) -> dict:
     return {
         "success": True,
         "latencyMs": ms_since(start),
+        "deletedCount": len(tracked_ids),
         "rawResponse": {"deleted": len(tracked_ids)},
         "note": f"Deleted {len(tracked_ids)} memories",
         "bridgeTiming": {
@@ -434,6 +650,10 @@ HANDLERS = {
     "add_memory": handle_add_memory,
     "search_memory": handle_search_memory,
     "get_memories": handle_get_memories,
+    "fetch_user_context": handle_fetch_user_context,
+    "fetch_customer_context": handle_fetch_customer_context,
+    "fetch_client_context": handle_fetch_client_context,
+    "get_context_for_prompt": handle_get_context_for_prompt,
     "delete_memory": handle_delete_memory,
     "shutdown": handle_shutdown,
 }
@@ -489,7 +709,7 @@ async def main() -> None:
             write_response({"id": req_id, "result": result, "error": None})
         except Exception as exc:
             logger.error("Handler error for %s: %s", method, traceback.format_exc())
-            write_response({"id": req_id, "result": None, "error": str(exc)})
+            write_response({"id": req_id, "result": None, "error": str(exc), "error_type": type(exc).__name__})
 
 
 if __name__ == "__main__":

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maximem/synap-js-sdk",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "description": "JavaScript wrapper around the Synap Python SDK",
   "main": "src/index.js",
   "types": "types/index.d.ts",

package/src/bridge-manager.js

@@ -7,6 +7,7 @@ const {
   resolveInstanceId,
   setupPythonRuntime,
 } = require('./runtime');
+const { createSynapError } = require('./errors');
 
 class BridgeManager {
   constructor(options = {}) {
@@ -147,7 +148,7 @@ class BridgeManager {
       this.pending.delete(payload.id);
 
       if (payload.error) {
-        pending.reject(new Error(payload.error));
+        pending.reject(createSynapError(payload.error, payload.error_type));
       } else {
         pending.resolve(payload.result);
       }