@maximem/synap-js-sdk 0.3.0 → 0.4.1

package/dist/chunk-5SC3ELNK.js

@@ -0,0 +1,856 @@
+// src/grpc/descriptor.ts
+var PROTO_SHA = "1a9a098645d1b3cf";
+var SYNAP_PROTO_DESCRIPTOR = {
+  "nested": {
+    "synap": {
+      "nested": {
+        "v1": {
+          "nested": {
+            "SynapService": {
+              "methods": {
+                "Listen": {
+                  "requestType": "StreamEvent",
+                  "requestStream": true,
+                  "responseType": "StreamResponse",
+                  "responseStream": true
+                },
+                "IngestTelemetry": {
+                  "requestType": "TelemetryEvent",
+                  "requestStream": true,
+                  "responseType": "TelemetryAck"
+                }
+              }
+            },
+            "StreamEvent": {
+              "oneofs": {
+                "payload": {
+                  "oneof": [
+                    "conversation_event",
+                    "heartbeat_ping",
+                    "session_control",
+                    "context_used",
+                    "context_assembled"
+                  ]
+                }
+              },
+              "fields": {
+                "conversation_event": {
+                  "type": "ConversationEvent",
+                  "id": 1
+                },
+                "heartbeat_ping": {
+                  "type": "HeartbeatPing",
+                  "id": 2
+                },
+                "session_control": {
+                  "type": "SessionControl",
+                  "id": 3
+                },
+                "context_used": {
+                  "type": "ContextUsedEvent",
+                  "id": 4
+                },
+                "context_assembled": {
+                  "type": "ContextAssembledEvent",
+                  "id": 5
+                }
+              }
+            },
+            "ContextUsedEvent": {
+              "fields": {
+                "bundle_id": {
+                  "type": "string",
+                  "id": 1
+                },
+                "conversation_id": {
+                  "type": "string",
+                  "id": 2
+                },
+                "user_id": {
+                  "type": "string",
+                  "id": 3
+                },
+                "customer_id": {
+                  "type": "string",
+                  "id": 4
+                },
+                "served_item_ids": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 5
+                },
+                "timestamp_ms": {
+                  "type": "int64",
+                  "id": 6
+                },
+                "scope": {
+                  "type": "string",
+                  "id": 7
+                },
+                "source_bundle_ids": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 8
+                }
+              }
+            },
+            "ContextAssembledEvent": {
+              "fields": {
+                "correlation_id": {
+                  "type": "string",
+                  "id": 1
+                },
+                "conversation_id": {
+                  "type": "string",
+                  "id": 2
+                },
+                "user_id": {
+                  "type": "string",
+                  "id": 3
+                },
+                "customer_id": {
+                  "type": "string",
+                  "id": 4
+                },
+                "final_item_ids": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 5
+                },
+                "final_total_tokens": {
+                  "type": "int32",
+                  "id": 6
+                },
+                "compaction_id": {
+                  "type": "string",
+                  "id": 7
+                },
+                "recent_turn_count": {
+                  "type": "int32",
+                  "id": 8
+                },
+                "compaction_end_timestamp": {
+                  "type": "string",
+                  "id": 9
+                },
+                "assembly_source": {
+                  "type": "string",
+                  "id": 10
+                },
+                "assembly_duration_ms": {
+                  "type": "int32",
+                  "id": 11
+                },
+                "cache_hit": {
+                  "type": "bool",
+                  "id": 12
+                },
+                "timestamp_ms": {
+                  "type": "int64",
+                  "id": 13
+                },
+                "sdk_version": {
+                  "type": "string",
+                  "id": 14
+                }
+              }
+            },
+            "ConversationEvent": {
+              "fields": {
+                "event_type": {
+                  "type": "string",
+                  "id": 1
+                },
+                "conversation_id": {
+                  "type": "string",
+                  "id": 2
+                },
+                "user_id": {
+                  "type": "string",
+                  "id": 3
+                },
+                "role": {
+                  "type": "string",
+                  "id": 4
+                },
+                "content": {
+                  "type": "string",
+                  "id": 5
+                },
+                "customer_id": {
+                  "type": "string",
+                  "id": 6
+                },
+                "session_id": {
+                  "type": "string",
+                  "id": 7
+                },
+                "metadata": {
+                  "keyType": "string",
+                  "type": "string",
+                  "id": 8
+                },
+                "timestamp_ms": {
+                  "type": "int64",
+                  "id": 9
+                },
+                "tool_name": {
+                  "type": "string",
+                  "id": 10
+                },
+                "tool_args_json": {
+                  "type": "string",
+                  "id": 11
+                },
+                "search_queries": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 12
+                },
+                "context_types": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 13
+                }
+              }
+            },
+            "HeartbeatPing": {
+              "fields": {
+                "timestamp_ms": {
+                  "type": "int64",
+                  "id": 1
+                }
+              }
+            },
+            "SessionControl": {
+              "fields": {
+                "action": {
+                  "type": "string",
+                  "id": 1
+                },
+                "session_id": {
+                  "type": "string",
+                  "id": 2
+                },
+                "conversation_id": {
+                  "type": "string",
+                  "id": 3
+                },
+                "user_id": {
+                  "type": "string",
+                  "id": 4
+                },
+                "customer_id": {
+                  "type": "string",
+                  "id": 5
+                }
+              }
+            },
+            "StreamResponse": {
+              "oneofs": {
+                "payload": {
+                  "oneof": [
+                    "context_bundle",
+                    "heartbeat_pong",
+                    "signal"
+                  ]
+                }
+              },
+              "fields": {
+                "context_bundle": {
+                  "type": "ContextBundleProto",
+                  "id": 1
+                },
+                "heartbeat_pong": {
+                  "type": "HeartbeatPong",
+                  "id": 2
+                },
+                "signal": {
+                  "type": "StreamSignal",
+                  "id": 3
+                }
+              }
+            },
+            "HeartbeatPong": {
+              "fields": {
+                "timestamp_ms": {
+                  "type": "int64",
+                  "id": 1
+                }
+              }
+            },
+            "StreamSignal": {
+              "fields": {
+                "signal_type": {
+                  "type": "string",
+                  "id": 1
+                },
+                "reason": {
+                  "type": "string",
+                  "id": 2
+                },
+                "metadata": {
+                  "keyType": "string",
+                  "type": "string",
+                  "id": 3
+                }
+              }
+            },
+            "ContextBundleProto": {
+              "fields": {
+                "bundle_id": {
+                  "type": "string",
+                  "id": 1
+                },
+                "decision_id": {
+                  "type": "string",
+                  "id": 2
+                },
+                "items_by_type": {
+                  "keyType": "string",
+                  "type": "ContextItemList",
+                  "id": 3
+                },
+                "total_tokens": {
+                  "type": "int32",
+                  "id": 4
+                },
+                "token_budget": {
+                  "type": "int32",
+                  "id": 5
+                },
+                "budget_exceeded": {
+                  "type": "bool",
+                  "id": 6
+                },
+                "retrieval_mode": {
+                  "type": "string",
+                  "id": 7
+                },
+                "sources_queried": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 8
+                },
+                "degradation_level": {
+                  "type": "string",
+                  "id": 9
+                },
+                "warnings": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 10
+                },
+                "created_at": {
+                  "type": "string",
+                  "id": 11
+                },
+                "retrieval_time_ms": {
+                  "type": "int32",
+                  "id": 12
+                },
+                "cache_hit": {
+                  "type": "bool",
+                  "id": 13
+                },
+                "search_queries": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 14
+                },
+                "anticipation_user_id": {
+                  "type": "string",
+                  "id": 15
+                },
+                "anticipation_customer_id": {
+                  "type": "string",
+                  "id": 16
+                },
+                "anticipation_conversation_id": {
+                  "type": "string",
+                  "id": 17
+                },
+                "search_keywords": {
+                  "rule": "repeated",
+                  "type": "string",
+                  "id": 18
+                },
+                "bundle_type": {
+                  "type": "string",
+                  "id": 19
+                },
+                "conversation_context": {
+                  "type": "ConversationContextProto",
+                  "id": 20
+                },
+                "bundle_confidence": {
+                  "type": "float",
+                  "id": 21
+                },
+                "origin_pattern_id": {
+                  "type": "string",
+                  "id": 22
+                },
+                "ttl_hint_seconds": {
+                  "type": "int32",
+                  "id": 23
+                }
+              }
+            },
+            "ConversationContextProto": {
+              "fields": {
+                "summary": {
+                  "type": "string",
+                  "id": 1
+                },
+                "current_state_json": {
+                  "type": "string",
+                  "id": 2
+                },
+                "key_extractions_json": {
+                  "type": "string",
+                  "id": 3
+                },
+                "recent_turns": {
+                  "rule": "repeated",
+                  "type": "RecentTurnProto",
+                  "id": 4
+                },
+                "compaction_id": {
+                  "type": "string",
+                  "id": 5
+                },
+                "compacted_at": {
+                  "type": "string",
+                  "id": 6
+                },
+                "conversation_id": {
+                  "type": "string",
+                  "id": 7
+                }
+              }
+            },
+            "RecentTurnProto": {
+              "fields": {
+                "role": {
+                  "type": "string",
+                  "id": 1
+                },
+                "content": {
+                  "type": "string",
+                  "id": 2
+                },
+                "timestamp": {
+                  "type": "string",
+                  "id": 3
+                }
+              }
+            },
+            "ContextItemList": {
+              "fields": {
+                "items": {
+                  "rule": "repeated",
+                  "type": "ContextItemProto",
+                  "id": 1
+                }
+              }
+            },
+            "ContextItemProto": {
+              "fields": {
+                "item_id": {
+                  "type": "string",
+                  "id": 1
+                },
+                "content": {
+                  "type": "string",
+                  "id": 2
+                },
+                "context_type": {
+                  "type": "string",
+                  "id": 3
+                },
+                "source": {
+                  "type": "string",
+                  "id": 4
+                },
+                "similarity_score": {
+                  "type": "float",
+                  "id": 5
+                },
+                "relevance_score": {
+                  "type": "float",
+                  "id": 6
+                },
+                "confidence": {
+                  "type": "float",
+                  "id": 7
+                },
+                "scope": {
+                  "type": "string",
+                  "id": 8
+                },
+                "entity_id": {
+                  "type": "string",
+                  "id": 9
+                },
+                "created_at": {
+                  "type": "string",
+                  "id": 10
+                },
+                "event_date": {
+                  "type": "string",
+                  "id": 11
+                },
+                "valid_until": {
+                  "type": "string",
+                  "id": 12
+                },
+                "temporal_category": {
+                  "type": "string",
+                  "id": 13
+                },
+                "temporal_confidence": {
+                  "type": "float",
+                  "id": 14
+                }
+              }
+            },
+            "TelemetryEvent": {
+              "fields": {
+                "event_type": {
+                  "type": "string",
+                  "id": 1
+                },
+                "instance_id": {
+                  "type": "string",
+                  "id": 2
+                },
+                "client_id": {
+                  "type": "string",
+                  "id": 3
+                },
+                "correlation_id": {
+                  "type": "string",
+                  "id": 4
+                },
+                "timestamp_ms": {
+                  "type": "int64",
+                  "id": 5
+                },
+                "latency_ms": {
+                  "type": "int32",
+                  "id": 6
+                },
+                "status": {
+                  "type": "string",
+                  "id": 7
+                },
+                "error_code": {
+                  "type": "string",
+                  "id": 8
+                },
+                "scope": {
+                  "type": "string",
+                  "id": 9
+                },
+                "cache_status": {
+                  "type": "string",
+                  "id": 10
+                },
+                "attempt": {
+                  "type": "int32",
+                  "id": 11
+                },
+                "http_method": {
+                  "type": "string",
+                  "id": 12
+                },
+                "http_path": {
+                  "type": "string",
+                  "id": 13
+                },
+                "http_status_code": {
+                  "type": "int32",
+                  "id": 14
+                },
+                "metadata": {
+                  "keyType": "string",
+                  "type": "string",
+                  "id": 15
+                },
+                "sdk_version": {
+                  "type": "string",
+                  "id": 16
+                },
+                "batch_id": {
+                  "type": "string",
+                  "id": 17
+                }
+              }
+            },
+            "TelemetryAck": {
+              "fields": {
+                "status": {
+                  "type": "string",
+                  "id": 1
+                },
+                "events_received": {
+                  "type": "int32",
+                  "id": 2
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+};
+
+// src/grpc/stream-client.ts
+var UNCACHEABLE_BUNDLE_TYPE = "reactive";
+var MAX_RECONNECT_ATTEMPTS = 10;
+var BACKOFF_BASE_MS = 1e3;
+var BACKOFF_MAX_MS = 3e4;
+var HEARTBEAT_INTERVAL_MS = 3e4;
+var HEARTBEAT_TIMEOUT_MS = 1e4;
+var MAX_MISSED_HEARTBEATS = 3;
+var MIN_TTL_SECONDS = 60;
+var GrpcStreamClient = class {
+  host;
+  port;
+  useTls;
+  #state = "disconnected";
+  #call = null;
+  #reconnectAttempts = 0;
+  #lastPongAt = 0;
+  #missedHeartbeats = 0;
+  #heartbeatTimer = null;
+  #shutdownRequested = false;
+  #grpc = null;
+  #ServiceStub = null;
+  #credentials;
+  #cache;
+  #options;
+  #sleep;
+  #connectTimeoutMs;
+  constructor(credentials, cache, options = {}) {
+    this.#credentials = credentials;
+    this.#cache = cache;
+    this.#options = options;
+    this.host = options.host ?? "synap-cloud-prod.maximem.ai";
+    this.port = options.port ?? 443;
+    this.useTls = options.useTls ?? true;
+    this.#sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    this.#connectTimeoutMs = options.connectTimeoutMs ?? 1e4;
+  }
+  get currentState() {
+    return this.#state;
+  }
+  get isConnected() {
+    return this.#state === "connected";
+  }
+  async connect() {
+    await this.#loadGrpc();
+    this.#shutdownRequested = false;
+    await this.#establish();
+    this.#startHeartbeat();
+  }
+  async disconnect() {
+    this.#shutdownRequested = true;
+    this.#stopHeartbeat();
+    this.#closeCall();
+    this.#setState("closed");
+  }
+  /** Fire-and-forget: a dropped event must never fail the caller's turn. */
+  sendConversationEvent(event) {
+    this.#write({ conversation_event: { ...event } });
+  }
+  sendSessionControl(input) {
+    this.#write({ session_control: { ...input } });
+  }
+  sendContextUsed(event) {
+    this.#write({ context_used: { ...event } });
+  }
+  sendContextAssembled(event) {
+    this.#write({ context_assembled: { ...event } });
+  }
+  #write(msg) {
+    if (!this.isConnected || this.#call === null) return;
+    try {
+      this.#call.write(msg);
+    } catch {
+    }
+  }
+  async #loadGrpc() {
+    if (this.#grpc !== null) return;
+    const [grpcMod, protoMod] = await Promise.all([
+      import(
+        /* @vite-ignore */
+        "@grpc/grpc-js"
+      ),
+      import(
+        /* @vite-ignore */
+        "@grpc/proto-loader"
+      )
+    ]);
+    this.#grpc = grpcMod;
+    const pkgDef = protoMod.fromJSON(
+      SYNAP_PROTO_DESCRIPTOR,
+      { keepCase: true, longs: Number, enums: String, defaults: true, oneofs: true }
+    );
+    const pkg = grpcMod.loadPackageDefinition(pkgDef);
+    this.#ServiceStub = pkg.synap.v1.SynapService;
+  }
+  async #establish() {
+    this.#setState("connecting");
+    const grpc = this.#grpc;
+    const Stub = this.#ServiceStub;
+    if (grpc === null || Stub === null) throw new Error("gRPC not loaded");
+    const channelCreds = this.useTls ? grpc.credentials.createSsl() : grpc.credentials.createInsecure();
+    const stub = new Stub(`${this.host}:${this.port}`, channelCreds, {
+      "grpc.keepalive_time_ms": 3e4,
+      "grpc.keepalive_timeout_ms": 1e4,
+      "grpc.keepalive_permit_without_calls": 1
+    });
+    await new Promise((resolve, reject) => {
+      const deadline = new Date(Date.now() + this.#connectTimeoutMs);
+      const waitForReady = stub.waitForReady;
+      if (typeof waitForReady !== "function") {
+        resolve();
+        return;
+      }
+      waitForReady.call(stub, deadline, (error) => {
+        if (error) reject(error);
+        else resolve();
+      });
+    });
+    const metadata = new grpc.Metadata();
+    metadata.add("authorization", `Bearer ${this.#credentials.apiKey}`);
+    metadata.add("x-client-id", this.#credentials.clientId);
+    metadata.add("x-instance-id", this.#credentials.instanceId);
+    const call = stub["Listen"](metadata);
+    call.on("data", (msg) => this.#handleMessage(msg));
+    call.on("error", (err) => {
+      void this.#handleDisconnect(`error: ${String(err)}`);
+    });
+    call.on("end", () => {
+      void this.#handleDisconnect("server_close");
+    });
+    this.#call = call;
+    this.#setState("connected");
+    this.#reconnectAttempts = 0;
+    this.#lastPongAt = Date.now();
+  }
+  #handleMessage(msg) {
+    if (msg["context_bundle"]) {
+      this.#handleBundle(msg["context_bundle"]);
+      return;
+    }
+    if (msg["heartbeat_pong"]) {
+      this.#lastPongAt = Date.now();
+      this.#missedHeartbeats = 0;
+      return;
+    }
+    const signal = msg["signal"];
+    if (signal?.signal_type === "closing") {
+      void this.#handleDisconnect("server_signal_closing");
+    }
+  }
+  #handleBundle(bundle) {
+    const bundleType = String(bundle["bundle_type"] ?? "") || "anticipation";
+    const conversationId = String(bundle["anticipation_conversation_id"] ?? "");
+    if (bundleType !== UNCACHEABLE_BUNDLE_TYPE) this.#store(bundle, bundleType, conversationId);
+    if (bundleType === "compaction_update" && conversationId !== "") {
+      this.#options.onCompactionUpdate?.(conversationId, bundle);
+    }
+    this.#options.onContext?.(bundle);
+  }
+  #store(bundle, bundleType, conversationId) {
+    const itemsByType = {};
+    for (const [type, list] of Object.entries(bundle["items_by_type"] ?? {})) {
+      const items = list?.items;
+      itemsByType[type] = items ?? [];
+    }
+    const ttlHint = Number(bundle["ttl_hint_seconds"] ?? 0);
+    this.#cache.store({
+      bundleId: String(bundle["bundle_id"] ?? ""),
+      // The cache keys on ONE entity. User id wins when present, so a bundle
+      // pushed for a user cannot be served to a different user in the same
+      // customer; falling back to customer id keeps org-scope bundles usable.
+      entityId: String(bundle["anticipation_user_id"] ?? "") || String(bundle["anticipation_customer_id"] ?? "") || null,
+      conversationId: conversationId || null,
+      itemsByType,
+      // 0 means "use the SDK default"; anything else is floored at 60s.
+      ttlHintSeconds: ttlHint > 0 ? Math.max(ttlHint, MIN_TTL_SECONDS) : null,
+      bundleType,
+      searchQueries: [
+        ...bundle["search_queries"] ?? [],
+        ...bundle["search_keywords"] ?? []
+      ]
+    });
+  }
+  async #handleDisconnect(_reason) {
+    if (this.#shutdownRequested) return;
+    this.#closeCall();
+    this.#setState("reconnecting");
+    if (this.#reconnectAttempts >= MAX_RECONNECT_ATTEMPTS) {
+      this.#setState("disconnected");
+      return;
+    }
+    const delay = Math.min(
+      BACKOFF_BASE_MS * 2 ** this.#reconnectAttempts + Math.random() * 1e3,
+      BACKOFF_MAX_MS
+    );
+    this.#reconnectAttempts += 1;
+    await this.#sleep(delay);
+    if (this.#shutdownRequested) return;
+    try {
+      await this.#establish();
+    } catch {
+      void this.#handleDisconnect("reconnect_failed");
+    }
+  }
+  #startHeartbeat() {
+    this.#heartbeatTimer = setInterval(() => {
+      if (!this.isConnected || this.#call === null) return;
+      const now = Date.now();
+      if (now - this.#lastPongAt > HEARTBEAT_TIMEOUT_MS) {
+        this.#missedHeartbeats += 1;
+        if (this.#missedHeartbeats >= MAX_MISSED_HEARTBEATS) {
+          void this.#handleDisconnect("heartbeat_timeout");
+          return;
+        }
+      }
+      try {
+        this.#call.write({ heartbeat_ping: { timestamp_ms: now } });
+      } catch {
+        void this.#handleDisconnect("heartbeat_write_error");
+      }
+    }, HEARTBEAT_INTERVAL_MS);
+    this.#heartbeatTimer.unref?.();
+  }
+  #stopHeartbeat() {
+    if (this.#heartbeatTimer !== null) {
+      clearInterval(this.#heartbeatTimer);
+      this.#heartbeatTimer = null;
+    }
+  }
+  #closeCall() {
+    try {
+      this.#call?.end();
+    } catch {
+    }
+    this.#call = null;
+  }
+  #setState(state) {
+    this.#state = state;
+    this.#options.onStateChange?.(state);
+  }
+};
+
+export {
+  PROTO_SHA,
+  GrpcStreamClient
+};
+//# sourceMappingURL=chunk-5SC3ELNK.js.map