@maximem/synap-js-sdk 0.5.9 → 0.5.11

package/dist/index.d.cts

@@ -1,5 +1,5 @@
-import { E as Encoder, a as AnticipationCacheSnapshot } from './errors-Bdayqlzy.cjs';
-export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as ExitReason, I as InsufficientCreditsError, j as InvalidConversationIdError, k as InvalidInputError, l as InvalidInstanceIdError, L as ListeningAlreadyActiveError, m as ListeningNotActiveError, n as LookupParams, o as LookupResult, p as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, q as SDKError, r as ServiceUnavailableError, s as SessionExpiredError, t as SnapshotBundle, u as SnapshotItemPreview, v as SnapshotItemRecord, S as SynapError, w as SynapErrorCode, x as SynapErrorOptions, y as SynapPermanentError, z as SynapTransientError, T as TranscriptConflictError, D as TransientError, F as isSynapError } from './errors-Bdayqlzy.cjs';
+import { E as Encoder, a as AnticipationCacheSnapshot } from './errors-BvUA5EW8.cjs';
+export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as CustomerIdNotAcceptedError, j as ExitReason, I as InsufficientCreditsError, k as InvalidConversationIdError, l as InvalidInputError, m as InvalidInstanceIdError, L as ListeningAlreadyActiveError, n as ListeningNotActiveError, o as LookupParams, p as LookupResult, q as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, r as SDKError, s as ServiceUnavailableError, t as SessionExpiredError, u as SnapshotBundle, v as SnapshotItemPreview, w as SnapshotItemRecord, S as SynapError, x as SynapErrorCode, y as SynapErrorOptions, z as SynapPermanentError, D as SynapTransientError, T as TranscriptConflictError, F as TransientError, G as isSynapError } from './errors-BvUA5EW8.cjs';
 
 /**
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -326,8 +326,21 @@ declare class HttpTransport {
      * deployment older than the field, and must mean "enforce nothing".
      */
     userContextIsolation: string | undefined;
-    /** Refuse a customer_id on a B2C instance, at the call site. */
-    checkCustomerId(customerId: unknown, where: string): void;
+    /**
+     * Set by the client to its identity resolution (`initialize()`'s whoami).
+     * Python refuses every call before `initialize()`; here the first request
+     * runs it instead, so a caller who skips it gets the same identity-dependent
+     * behaviour (client-scope cache hits, the B2C check) rather than an error.
+     */
+    identityResolver: (() => Promise<void>) | undefined;
+    /** Resolve identity once, before the first request. Never throws. */
+    ready(): Promise<void>;
+    /**
+     * Refuse a customer_id on a B2C instance, at the call site. Resolves identity
+     * first: the isolation comes from whoami, so on the first call of a client
+     * that skipped initialize() the check would otherwise see nothing and pass.
+     */
+    checkCustomerId(customerId: unknown, where: string): Promise<void>;
     setTimeouts(timeouts: Partial<TimeoutConfig>): void;
     /**
      * `null` DISABLES retries, matching Python.
@@ -1759,12 +1772,16 @@ declare class SynapClient {
     /**
      * Resolve `client_id` and `instance_id` from the API key.
      *
-     * Mirrors Python's `initialize()`. Calling it is optional here (unlike
-     * Python, which raises "SDK not initialized" from `_ensure_initialized`)
-     * because every HTTP route authenticates on the API key alone. It matters
-     * for the anticipation cache: a bundle shared at client scope is filtered on
-     * `client_id`, and an empty one fails that filter for every bundle. That was
-     * a silent cache-scope bug in Python before whoami bootstrapping existed.
+     * Mirrors Python's `initialize()`. Python raises "SDK not initialized" on
+     * any call made before it; here the first request runs the same resolution
+     * instead (`identityResolver` on the transport), so skipping this call costs
+     * nothing and breaks no existing caller. It matters for the anticipation
+     * cache: a bundle shared at client scope is filtered on `client_id`, and an
+     * empty one fails that filter for every bundle.
+     *
+     * Calling it explicitly still locks `configure()`, as in Python. Resolving
+     * on first use does not, because a caller who never called it could always
+     * configure after a request, and that keeps working.
      *
      * Best-effort and idempotent. A whoami failure leaves whatever the
      * constructor resolved and is not fatal.
@@ -1856,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.9";
+declare const SDK_VERSION = "0.5.11";
 
 /**
  * `response_shape: "ranked"`: one list in the order the server ranked it.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { E as Encoder, a as AnticipationCacheSnapshot } from './errors-Bdayqlzy.js';
-export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as ExitReason, I as InsufficientCreditsError, j as InvalidConversationIdError, k as InvalidInputError, l as InvalidInstanceIdError, L as ListeningAlreadyActiveError, m as ListeningNotActiveError, n as LookupParams, o as LookupResult, p as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, q as SDKError, r as ServiceUnavailableError, s as SessionExpiredError, t as SnapshotBundle, u as SnapshotItemPreview, v as SnapshotItemRecord, S as SynapError, w as SynapErrorCode, x as SynapErrorOptions, y as SynapPermanentError, z as SynapTransientError, T as TranscriptConflictError, D as TransientError, F as isSynapError } from './errors-Bdayqlzy.js';
+import { E as Encoder, a as AnticipationCacheSnapshot } from './errors-BvUA5EW8.js';
+export { b as ANY_SCOPE, c as AgentUnavailableError, A as AnticipationCache, d as AnticipationCacheOptions, e as AuthenticationError, B as BundleItem, C as ConflictError, f as ConnectionError, g as ContextBundle, h as ContextNotFoundError, i as CustomerIdNotAcceptedError, j as ExitReason, I as InsufficientCreditsError, k as InvalidConversationIdError, l as InvalidInputError, m as InvalidInstanceIdError, L as ListeningAlreadyActiveError, n as ListeningNotActiveError, o as LookupParams, p as LookupResult, q as LookupTelemetry, N as NetworkTimeoutError, P as PermanentError, R as RateLimitError, r as SDKError, s as ServiceUnavailableError, t as SessionExpiredError, u as SnapshotBundle, v as SnapshotItemPreview, w as SnapshotItemRecord, S as SynapError, x as SynapErrorCode, y as SynapErrorOptions, z as SynapPermanentError, D as SynapTransientError, T as TranscriptConflictError, F as TransientError, G as isSynapError } from './errors-BvUA5EW8.js';
 
 /**
  * AUTOGENERATED FROM synap/sdk/CONTRACT/endpoints.yaml -- DO NOT EDIT.
@@ -326,8 +326,21 @@ declare class HttpTransport {
      * deployment older than the field, and must mean "enforce nothing".
      */
     userContextIsolation: string | undefined;
-    /** Refuse a customer_id on a B2C instance, at the call site. */
-    checkCustomerId(customerId: unknown, where: string): void;
+    /**
+     * Set by the client to its identity resolution (`initialize()`'s whoami).
+     * Python refuses every call before `initialize()`; here the first request
+     * runs it instead, so a caller who skips it gets the same identity-dependent
+     * behaviour (client-scope cache hits, the B2C check) rather than an error.
+     */
+    identityResolver: (() => Promise<void>) | undefined;
+    /** Resolve identity once, before the first request. Never throws. */
+    ready(): Promise<void>;
+    /**
+     * Refuse a customer_id on a B2C instance, at the call site. Resolves identity
+     * first: the isolation comes from whoami, so on the first call of a client
+     * that skipped initialize() the check would otherwise see nothing and pass.
+     */
+    checkCustomerId(customerId: unknown, where: string): Promise<void>;
     setTimeouts(timeouts: Partial<TimeoutConfig>): void;
     /**
      * `null` DISABLES retries, matching Python.
@@ -1759,12 +1772,16 @@ declare class SynapClient {
     /**
      * Resolve `client_id` and `instance_id` from the API key.
      *
-     * Mirrors Python's `initialize()`. Calling it is optional here (unlike
-     * Python, which raises "SDK not initialized" from `_ensure_initialized`)
-     * because every HTTP route authenticates on the API key alone. It matters
-     * for the anticipation cache: a bundle shared at client scope is filtered on
-     * `client_id`, and an empty one fails that filter for every bundle. That was
-     * a silent cache-scope bug in Python before whoami bootstrapping existed.
+     * Mirrors Python's `initialize()`. Python raises "SDK not initialized" on
+     * any call made before it; here the first request runs the same resolution
+     * instead (`identityResolver` on the transport), so skipping this call costs
+     * nothing and breaks no existing caller. It matters for the anticipation
+     * cache: a bundle shared at client scope is filtered on `client_id`, and an
+     * empty one fails that filter for every bundle.
+     *
+     * Calling it explicitly still locks `configure()`, as in Python. Resolving
+     * on first use does not, because a caller who never called it could always
+     * configure after a request, and that keeps working.
      *
      * Best-effort and idempotent. A whoami failure leaves whatever the
      * constructor resolved and is not fatal.
@@ -1856,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.9";
+declare const SDK_VERSION = "0.5.11";
 
 /**
  * `response_shape: "ranked"`: one list in the order the server ranked it.

package/dist/index.js

@@ -20,6 +20,7 @@ import {
   ConflictError,
   ConnectionError,
   ContextNotFoundError,
+  CustomerIdNotAcceptedError,
   InsufficientCreditsError,
   InvalidConversationIdError,
   InvalidInputError,
@@ -39,7 +40,7 @@ import {
   TransientError,
   isSynapError,
   newCorrelationId
-} from "./chunk-BWMPKLFG.js";
+} from "./chunk-4GE7SORD.js";
 
 // src/transport/endpoints.ts
 var ENDPOINTS = {
@@ -194,9 +195,7 @@ var B2C_ISOLATION = "equals_customer";
 function checkCustomerId(isolation, customerId, where, instanceId) {
   if (customerId === void 0 || customerId === null || customerId === "") return;
   if (isolation !== B2C_ISOLATION) return;
-  throw new InvalidInputError(
-    `${where}: customer_id is not accepted on this instance${instanceId ? ` (${instanceId})` : ""}, which is B2C (user_context_isolation='${B2C_ISOLATION}'). Send user_id only; it is the whole identity, and the server files and reads your data under it. Received customer_id=${JSON.stringify(customerId)}.`
-  );
+  throw new CustomerIdNotAcceptedError(where, String(customerId), instanceId);
 }
 
 // src/transport/http.ts
@@ -267,8 +266,24 @@ var HttpTransport = class {
    * deployment older than the field, and must mean "enforce nothing".
    */
   userContextIsolation = void 0;
-  /** Refuse a customer_id on a B2C instance, at the call site. */
-  checkCustomerId(customerId, where) {
+  /**
+   * Set by the client to its identity resolution (`initialize()`'s whoami).
+   * Python refuses every call before `initialize()`; here the first request
+   * runs it instead, so a caller who skips it gets the same identity-dependent
+   * behaviour (client-scope cache hits, the B2C check) rather than an error.
+   */
+  identityResolver = void 0;
+  /** Resolve identity once, before the first request. Never throws. */
+  async ready() {
+    if (this.identityResolver !== void 0) await this.identityResolver();
+  }
+  /**
+   * Refuse a customer_id on a B2C instance, at the call site. Resolves identity
+   * first: the isolation comes from whoami, so on the first call of a client
+   * that skipped initialize() the check would otherwise see nothing and pass.
+   */
+  async checkCustomerId(customerId, where) {
+    await this.ready();
     checkCustomerId(
       this.userContextIsolation,
       customerId,
@@ -298,6 +313,7 @@ var HttpTransport = class {
     const spec = ENDPOINTS[name];
     const correlationId = options.correlationId ?? newCorrelationId();
     const idempotent = options.idempotent ?? spec.idempotent;
+    if (name !== "whoami") await this.ready();
     let attempt = 0;
     let last = null;
     while (attempt < this.retryPolicy.maxAttempts) {
@@ -619,11 +635,10 @@ function buildFetchRequest(scope, options) {
   const conversationId = opt(options, "conversation_id", "conversationId");
   const searchQuery = opt(options, "search_query", "searchQuery");
   const maxResults = opt(options, "max_results", "maxResults") ?? 10;
-  const precisionLevel = opt(options, "precision_level", "precisionLevel") ?? "high";
   const queryDate = opt(options, "query_date", "queryDate");
   const perQuery = opt(options, "max_results_per_query", "maxResultsPerQuery");
   const responseShape = responseShapeOf(options);
-  const mode = options.mode ?? "fast";
+  const { mode, precisionLevel } = retrievalOptionsOf(options);
   if (searchQuery !== void 0 && !Array.isArray(searchQuery)) {
     throw new InvalidInputError("search_query must be an array when provided");
   }
@@ -644,13 +659,15 @@ function buildFetchRequest(scope, options) {
   if (options.include_conversation_context === false) {
     body["include_conversation_context"] = false;
   }
+  const scopePath = opt(options, "scope_path", "scopePath");
+  if (scopePath !== void 0 && scopePath !== null && Object.keys(scopePath).length > 0) {
+    body["scope"] = scopePath;
+  }
   switch (scope) {
     case "user":
       {
         if (!userId) throw new InvalidInputError("user_id is required");
         body["user_id"] = userId;
-        const scopePath = opt(options, "scope_path", "scopePath");
-        if (scopePath !== void 0) body["scope"] = scopePath;
         const contextMode = opt(options, "context_mode", "contextMode") ?? "in-conversation";
         if (!VALID_CONTEXT_MODES.includes(contextMode)) {
           throw new InvalidInputError(
@@ -697,13 +714,32 @@ function responseShapeOf(options) {
   }
   return shape;
 }
+var VALID_MODES = ["fast", "accurate"];
+var VALID_PRECISION = ["high", "medium"];
+function retrievalOptionsOf(options) {
+  const mode = options.mode ?? "fast";
+  if (!VALID_MODES.includes(mode)) {
+    throw new InvalidInputError(
+      `Invalid mode '${mode}'. Must be one of: ${VALID_MODES.join(", ")}`
+    );
+  }
+  const precisionLevel = opt(options, "precision_level", "precisionLevel") ?? "high";
+  if (!VALID_PRECISION.includes(precisionLevel)) {
+    throw new InvalidInputError(
+      `Invalid precision_level '${precisionLevel}'. Must be one of: ${VALID_PRECISION.join(", ")}`
+    );
+  }
+  return { mode, precisionLevel };
+}
 async function fetchContext(transport, scope, options = {}, hooks = {}) {
   const startedAt = Date.now();
-  transport.checkCustomerId(
+  await transport.ready?.();
+  await transport.checkCustomerId(
     opt(options, "customer_id", "customerId"),
     `${scope}.context.fetch`
   );
   const responseShape = responseShapeOf(options);
+  retrievalOptionsOf(options);
   const network = async () => {
     const { endpoint, body } = buildFetchRequest(scope, options);
     const result = await transport.request(endpoint, { body });
@@ -1046,7 +1082,7 @@ function createMemoriesInterface(transport, onForgotten) {
   return {
     async create(options) {
       const o2 = options;
-      transport.checkCustomerId(o2["customer_id"] ?? o2["customerId"], "memories.create");
+      await transport.checkCustomerId(o2["customer_id"] ?? o2["customerId"], "memories.create");
       return transport.request("memories_create", { body: buildCreateBody(options) });
     },
     async batch_create(options) {
@@ -1063,7 +1099,7 @@ function createMemoriesInterface(transport, onForgotten) {
       const userId = options.user_id ?? options.userId;
       const customerId = options.customer_id ?? options.customerId;
       if (!userId) throw new InvalidInputError("user_id is required");
-      transport.checkCustomerId(customerId, "memories.create_from_file");
+      await transport.checkCustomerId(customerId, "memories.create_from_file");
       const filePath = options.file_path ?? options.filePath;
       const sources = [filePath, options.file, options.text].filter((v) => v !== void 0);
       if (sources.length === 0) {
@@ -1130,7 +1166,7 @@ function createMemoriesInterface(transport, onForgotten) {
     },
     async forget(options) {
       const o2 = options;
-      transport.checkCustomerId(o2["customer_id"] ?? o2["customerId"], "memories.forget");
+      await transport.checkCustomerId(o2["customer_id"] ?? o2["customerId"], "memories.forget");
       const body = buildForgetBody(options);
       const result = await transport.request("memories_forget", { body });
       const removed = !!result?.deleted_ids?.length || result?.status === "deleted" || result?.status === "partial";
@@ -1401,7 +1437,7 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
   };
   return {
     async record_message(options) {
-      transport.checkCustomerId(
+      await transport.checkCustomerId(
         options["customer_id"] ?? options["customerId"],
         "conversation.record_message"
       );
@@ -1433,7 +1469,7 @@ function createConversationNamespace(transport, subscribers = new CompactionSubs
       }
       for (const m of messages) {
         const mo = m;
-        transport.checkCustomerId(
+        await transport.checkCustomerId(
           mo["customer_id"] ?? mo["customerId"],
           "conversation.record_messages_batch"
         );
@@ -1743,7 +1779,7 @@ function createInstanceNamespace(credentials, cache, onTurn, agentModel = () =>
         onListen?.();
       } catch {
       }
-      const { GrpcStreamClient } = await import("./stream-client-3WHXGW4U.js");
+      const { GrpcStreamClient } = await import("./stream-client-ZBCKRU7S.js");
       const onContext = options.on_context ?? options.onContext;
       const onDisconnect = options.on_disconnect ?? options.onDisconnect;
       const onReconnect = options.on_reconnect ?? options.onReconnect;
@@ -1922,7 +1958,7 @@ function createInstanceNamespace(credentials, cache, onTurn, agentModel = () =>
 }
 
 // src/version.ts
-var SDK_VERSION = "0.5.9";
+var SDK_VERSION = "0.5.11";
 
 // src/registry.ts
 var instances = /* @__PURE__ */ new Map();
@@ -3648,6 +3684,7 @@ var SynapClient = class _SynapClient {
   instance;
   #closed = false;
   #initialized = false;
+  #identity;
   #registryKeys;
   #compactionSubscribers;
   #shortTerm;
@@ -3698,6 +3735,7 @@ var SynapClient = class _SynapClient {
       userAgent: `@maximem/synap-js-sdk/${SDK_VERSION}`
     });
     if (options.heartbeat) this.#transport.startHeartbeat();
+    this.#transport.identityResolver = () => this.#resolveIdentity();
     this.#anticipationCache = new AnticipationCache();
     this.#fetchHooks = {
       beforeFetch: async (scope, options2) => {
@@ -3903,19 +3941,30 @@ var SynapClient = class _SynapClient {
   /**
    * Resolve `client_id` and `instance_id` from the API key.
    *
-   * Mirrors Python's `initialize()`. Calling it is optional here (unlike
-   * Python, which raises "SDK not initialized" from `_ensure_initialized`)
-   * because every HTTP route authenticates on the API key alone. It matters
-   * for the anticipation cache: a bundle shared at client scope is filtered on
-   * `client_id`, and an empty one fails that filter for every bundle. That was
-   * a silent cache-scope bug in Python before whoami bootstrapping existed.
+   * Mirrors Python's `initialize()`. Python raises "SDK not initialized" on
+   * any call made before it; here the first request runs the same resolution
+   * instead (`identityResolver` on the transport), so skipping this call costs
+   * nothing and breaks no existing caller. It matters for the anticipation
+   * cache: a bundle shared at client scope is filtered on `client_id`, and an
+   * empty one fails that filter for every bundle.
+   *
+   * Calling it explicitly still locks `configure()`, as in Python. Resolving
+   * on first use does not, because a caller who never called it could always
+   * configure after a request, and that keeps working.
    *
    * Best-effort and idempotent. A whoami failure leaves whatever the
    * constructor resolved and is not fatal.
    */
   async initialize() {
-    if (this.#initialized) return;
     this.#initialized = true;
+    await this.#resolveIdentity();
+  }
+  /** Runs whoami at most once, however many calls arrive together. */
+  #resolveIdentity() {
+    this.#identity ??= this.#whoami();
+    return this.#identity;
+  }
+  async #whoami() {
     const credentials = this.#transport.currentCredentials();
     if (credentials.clientId !== "" && credentials.instanceId !== "") return;
     try {
@@ -4019,6 +4068,7 @@ var SynapClient = class _SynapClient {
       last_n_conversations: lastNConversations = 1,
       response_shape: responseShape = "by_type"
     } = options;
+    await this.#transport.checkCustomerId(customerId, "sdk.fetch");
     validateConversationId(conversationId);
     responseShapeOf({ response_shape: responseShape });
     const wants = (scope) => scopes === void 0 || scopes.includes(scope);
@@ -4414,6 +4464,7 @@ export {
   ConflictError,
   ConnectionError,
   ContextNotFoundError,
+  CustomerIdNotAcceptedError,
   DEFAULT_BASE_URL,
   DEFAULT_DOCUMENT_TYPE,
   DEFAULT_INGEST_MODE,