@maximem/synap-js-sdk 0.5.11 → 0.5.13

package/dist/index.d.cts

@@ -949,6 +949,16 @@ interface WaitOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * Scope-aware context fetching.
+ *
+ * Scopes are client > customer > user. `conversation_id` is NOT a tier: it
+ * groups turns within a scope. Passing it narrows an existing scope rather
+ * than selecting a different one.
+ */
+
+type Scope = 'user' | 'customer' | 'client' | 'conversation';
+
 /**
  * Conversation namespace. Mirrors `ConversationInterface` and
  * `ConversationContextInterface` in the Python SDK.
@@ -1106,16 +1116,6 @@ type WriteInvalidator = (ids: {
     customerId?: string | undefined;
 }) => void;
 
-/**
- * Scope-aware context fetching.
- *
- * Scopes are client > customer > user. `conversation_id` is NOT a tier: it
- * groups turns within a scope. Passing it narrows an existing scope rather
- * than selecting a different one.
- */
-
-type Scope = 'user' | 'customer' | 'client' | 'conversation';
-
 /** User namespace. Mirrors `UserInterface` in the Python SDK. */
 
 interface UserNamespace {
@@ -1873,7 +1873,7 @@ declare class SynapClient {
  * build when the two disagree, which is the only thing that makes a manual
  * publish safe.
  */
-declare const SDK_VERSION = "0.5.11";
+declare const SDK_VERSION = "0.5.13";
 
 /**
  * `response_shape: "ranked"`: one list in the order the server ranked it.

package/dist/index.d.ts

@@ -949,6 +949,16 @@ interface WaitOptions {
     signal?: AbortSignal;
 }
 
+/**
+ * Scope-aware context fetching.
+ *
+ * Scopes are client > customer > user. `conversation_id` is NOT a tier: it
+ * groups turns within a scope. Passing it narrows an existing scope rather
+ * than selecting a different one.
+ */
+
+type Scope = 'user' | 'customer' | 'client' | 'conversation';
+
 /**
  * Conversation namespace. Mirrors `ConversationInterface` and
  * `ConversationContextInterface` in the Python SDK.
@@ -1106,16 +1116,6 @@ type WriteInvalidator = (ids: {
     customerId?: string | undefined;
 }) => void;
 
-/**
- * Scope-aware context fetching.
- *
- * Scopes are client > customer > user. `conversation_id` is NOT a tier: it
- * groups turns within a scope. Passing it narrows an existing scope rather
- * than selecting a different one.
- */
-
-type Scope = 'user' | 'customer' | 'client' | 'conversation';
-
 /** User namespace. Mirrors `UserInterface` in the Python SDK. */
 
 interface UserNamespace {
@@ -1873,7 +1873,7 @@ declare class SynapClient {
  * build when the two disagree, which is the only thing that makes a manual
  * publish safe.
  */
-declare const SDK_VERSION = "0.5.11";
+declare const SDK_VERSION = "0.5.13";
 
 /**
  * `response_shape: "ranked"`: one list in the order the server ranked it.

package/dist/index.js

@@ -408,13 +408,25 @@ function isOutcomeUnknown(error) {
   if (error instanceof ConflictError) return false;
   if (error instanceof InsufficientCreditsError) return false;
   if (error instanceof ContextNotFoundError) return false;
-  if (error instanceof NetworkTimeoutError) return true;
   if (isConnectionRefusal(error)) return false;
+  if (error instanceof NetworkTimeoutError) return true;
   return true;
 }
+var CONNECTION_REFUSAL_CODES = /* @__PURE__ */ new Set([
+  "ECONNREFUSED",
+  "ENOTFOUND",
+  "EAI_AGAIN",
+  "ECONNRESET",
+  "EHOSTUNREACH"
+]);
 function isConnectionRefusal(error) {
-  const code = error?.cause?.code ?? error?.code;
-  return code === "ECONNREFUSED" || code === "ENOTFOUND" || code === "EAI_AGAIN" || code === "ECONNRESET" || code === "EHOSTUNREACH";
+  let cur = error;
+  for (let depth = 0; depth < 4 && cur !== null && typeof cur === "object"; depth += 1) {
+    const code = cur.code;
+    if (typeof code === "string" && CONNECTION_REFUSAL_CODES.has(code)) return true;
+    cur = cur.cause;
+  }
+  return false;
 }
 function toTransportError(error, correlationId) {
   if (error instanceof SynapError) return error;
@@ -422,6 +434,12 @@ function toTransportError(error, correlationId) {
   if (name === "AbortError" || name === "TimeoutError") {
     return new NetworkTimeoutError("Request timed out", { correlationId, cause: error });
   }
+  if (isConnectionRefusal(error)) {
+    return new NetworkTimeoutError(
+      `Connection failed: ${error?.message ?? String(error)}`,
+      { correlationId, cause: error }
+    );
+  }
   return new ServiceUnavailableError(
     `Network request failed: ${error?.message ?? String(error)}`,
     { correlationId, cause: error }
@@ -639,6 +657,7 @@ function buildFetchRequest(scope, options) {
   const perQuery = opt(options, "max_results_per_query", "maxResultsPerQuery");
   const responseShape = responseShapeOf(options);
   const { mode, precisionLevel } = retrievalOptionsOf(options);
+  const { contextMode, lastN } = scopeOptionsOf(scope, options);
   if (searchQuery !== void 0 && !Array.isArray(searchQuery)) {
     throw new InvalidInputError("search_query must be an array when provided");
   }
@@ -666,21 +685,7 @@ function buildFetchRequest(scope, options) {
   switch (scope) {
     case "user":
       {
-        if (!userId) throw new InvalidInputError("user_id is required");
         body["user_id"] = userId;
-        const contextMode = opt(options, "context_mode", "contextMode") ?? "in-conversation";
-        if (!VALID_CONTEXT_MODES.includes(contextMode)) {
-          throw new InvalidInputError(
-            `Invalid context_mode '${contextMode}'. Must be one of: ${VALID_CONTEXT_MODES.join(", ")}`
-          );
-        }
-        const lastN = opt(options, "last_n_conversations", "lastNConversations") ?? 1;
-        if (!Number.isInteger(lastN)) {
-          throw new InvalidInputError("last_n_conversations must be an integer");
-        }
-        if (lastN < 0 || lastN > 20) {
-          throw new InvalidInputError("last_n_conversations must be between 0 and 20");
-        }
         if (contextMode === "conversation-summary") {
           body["context_mode"] = contextMode;
           body["include_profile"] = opt(options, "include_profile", "includeProfile") ?? true;
@@ -691,11 +696,9 @@ function buildFetchRequest(scope, options) {
       }
       break;
     case "customer":
-      if (!customerId) throw new InvalidInputError("customer_id is required");
       body["customer_id"] = customerId;
       break;
     case "conversation":
-      if (!conversationId) throw new InvalidInputError("conversation_id is required");
       if (userId !== void 0) body["user_id"] = userId;
       if (customerId !== void 0) body["customer_id"] = customerId;
       break;
@@ -714,6 +717,33 @@ function responseShapeOf(options) {
   }
   return shape;
 }
+var REQUIRED_ID = {
+  user: ["user_id", "userId"],
+  customer: ["customer_id", "customerId"],
+  conversation: ["conversation_id", "conversationId"],
+  client: null
+};
+function scopeOptionsOf(scope, options) {
+  const required = REQUIRED_ID[scope];
+  if (required !== null && !opt(options, required[0], required[1])) {
+    throw new InvalidInputError(`${required[0]} is required`);
+  }
+  const contextMode = opt(options, "context_mode", "contextMode") ?? "in-conversation";
+  const lastN = opt(options, "last_n_conversations", "lastNConversations") ?? 1;
+  if (scope !== "user") return { contextMode, lastN };
+  if (!VALID_CONTEXT_MODES.includes(contextMode)) {
+    throw new InvalidInputError(
+      `Invalid context_mode '${contextMode}'. Must be one of: ${VALID_CONTEXT_MODES.join(", ")}`
+    );
+  }
+  if (!Number.isInteger(lastN)) {
+    throw new InvalidInputError("last_n_conversations must be an integer");
+  }
+  if (lastN < 0 || lastN > 20) {
+    throw new InvalidInputError("last_n_conversations must be between 0 and 20");
+  }
+  return { contextMode, lastN };
+}
 var VALID_MODES = ["fast", "accurate"];
 var VALID_PRECISION = ["high", "medium"];
 function retrievalOptionsOf(options) {
@@ -740,12 +770,23 @@ async function fetchContext(transport, scope, options = {}, hooks = {}) {
   );
   const responseShape = responseShapeOf(options);
   retrievalOptionsOf(options);
+  const { contextMode } = scopeOptionsOf(scope, options);
+  const summaryMode = scope === "user" && contextMode === "conversation-summary";
+  const finish = (response2) => {
+    hooks.onResponse?.(scope, options, response2);
+    return response2;
+  };
+  const conversationId = opt(options, "conversation_id", "conversationId");
+  const skipServerSt = conversationId ? hooks.skipServerShortTerm?.(conversationId) === true : false;
   const network = async () => {
-    const { endpoint, body } = buildFetchRequest(scope, options);
+    const { endpoint, body } = buildFetchRequest(
+      scope,
+      skipServerSt ? { ...options, include_conversation_context: false } : options
+    );
     const result = await transport.request(endpoint, { body });
     return applyResponseShape(result?.["context"] ?? {}, responseShape);
   };
-  const anticipated = await hooks.beforeFetch?.(scope, options) ?? null;
+  const anticipated = summaryMode ? null : await hooks.beforeFetch?.(scope, options) ?? null;
   if (anticipated !== null && anticipated.borderline) {
     const pending = network();
     pending.catch(() => void 0);
@@ -757,17 +798,17 @@ async function fetchContext(transport, scope, options = {}, hooks = {}) {
     if (timer !== void 0) clearTimeout(timer);
     if (won !== null) {
       hooks.onAssembled?.(scope, options, won, startedAt);
-      return won;
+      return finish(won);
     }
   }
   if (anticipated !== null) {
     hooks.onServedFromCache?.(scope, options, anticipated);
     hooks.onAssembled?.(scope, options, anticipated.response, startedAt);
-    return applyResponseShape(anticipated.response, responseShape);
+    return finish(applyResponseShape(anticipated.response, responseShape));
   }
   const response = await network();
   hooks.onAssembled?.(scope, options, response, startedAt);
-  return response;
+  return finish(response);
 }
 
 // src/context/normalize.ts
@@ -1402,7 +1443,7 @@ function storedBatchRows(bodies, result) {
 function createConversationNamespace(transport, subscribers = new CompactionSubscribers(), onWrite = () => {
 }, onTurn = () => {
 }, onFetched = () => {
-}, localShortTerm = { prompt: () => null, compacted: () => null }, agentModel = () => ({})) {
+}, localShortTerm = { prompt: () => null, compacted: () => null }, agentModel = () => ({}), fetchHooks = {}) {
   const writesInFlight = /* @__PURE__ */ new Map();
   const withTurnModel = (body, options) => {
     const metadata = withAgentModel(
@@ -1509,7 +1550,7 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
       async fetch(options = {}) {
         const id = options.conversation_id ?? options.conversationId;
         validateConversationId(id);
-        const response = await fetchContext(transport, "conversation", options);
+        const response = await fetchContext(transport, "conversation", options, fetchHooks);
         onFetched(
           response,
           id,
@@ -1958,7 +1999,7 @@ function createInstanceNamespace(credentials, cache, onTurn, agentModel = () =>
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.11";
+var SDK_VERSION = "0.5.13";
 
 // src/registry.ts
 var instances = /* @__PURE__ */ new Map();
@@ -3776,6 +3817,29 @@ var SynapClient = class _SynapClient {
       },
       onServedFromCache: (_scope, options2, served) => {
         this.#emitContextUsed(options2, _scope, served);
+      },
+      // The periodic user-summary splice, as Python runs it at the end of the
+      // user, customer and client fetches (the conversation fetch does its own
+      // through `onFetched`). Until 0.5.12 only the conversation fetch had it,
+      // so the same usage gave the model different context in JS.
+      // Python's `_should_skip_server_st`: when this process already holds the
+      // conversation's compaction and every turn after it, the server is told
+      // not to assemble them again.
+      skipServerShortTerm: (conversationId) => {
+        if (!this.#isStAuthoritative()) return false;
+        const entry = this.#shortTerm.get(conversationId);
+        return entry !== null && entry.compactionId !== null && isComplete(entry);
+      },
+      onResponse: (scope, options2, response) => {
+        if (scope === "conversation") return;
+        const o2 = options2;
+        const owner = scope === "user" ? o2["user_id"] ?? o2["userId"] : scope === "customer" ? o2["customer_id"] ?? o2["customerId"] : "_client";
+        this.#injectUserSummary(
+          response,
+          o2["conversation_id"] ?? o2["conversationId"],
+          owner,
+          rungKey(o2["scope_path"] ?? o2["scopePath"])
+        );
       }
     };
     this.user = createUserNamespace(this.#transport, this.#fetchHooks);
@@ -3829,7 +3893,12 @@ var SynapClient = class _SynapClient {
         reseed: (conversationId, response) => this.#reseedShortTerm(conversationId, response),
         historyExcerpts: (conversationId, response, query) => this.#withHistoryExcerpts(conversationId, response, query)
       },
-      () => this.#agentModel
+      () => this.#agentModel,
+      // The same hooks as the other three scopes: the anticipation cache first,
+      // as Python's conversation fetch does, and the audit events. Until 0.5.13
+      // the conversation fetch was built without them, so every JS conversation
+      // fetch was a billed round trip, including ones the stream had answered.
+      this.#fetchHooks
     );
     this.memories = createMemoriesInterface(this.#transport, ({ userId, customerId }) => {
       for (const id of /* @__PURE__ */ new Set([userId, customerId])) {
@@ -4443,7 +4512,7 @@ function resolveBaseUrl(options) {
 function resolveCredentials(options) {
   const apiKey = options.apiKey ?? getEnv("SYNAP_API_KEY");
   if (!apiKey) {
-    throw new InvalidInputError(
+    throw new AuthenticationError(
       "No Synap API key found. Set SYNAP_API_KEY in your environment, or pass apiKey to the SynapClient constructor."
     );
   }