@anuma/sdk 9.1.0 → 9.1.1

package/dist/react/index.d.ts

@@ -11607,7 +11607,8 @@ declare class RemoteMemoryError extends Error {
     readonly status: number;
     readonly code?: string | undefined;
     readonly retryAfterMs?: number | undefined;
-    constructor(message: string, status: number, code?: string | undefined, retryAfterMs?: number | undefined);
+    readonly rateLimitBucket?: string | undefined;
+    constructor(message: string, status: number, code?: string | undefined, retryAfterMs?: number | undefined, rateLimitBucket?: string | undefined);
 }
 /**
  * Remote persistence foundation for MemoryStore, not yet its recall/retain implementation.
@@ -11616,6 +11617,7 @@ declare class RemoteMemoryError extends Error {
  * Migration must have activated the account under the canonical key before construction.
  */
 interface RemoteMemoryPersistence extends RemoteTopicPersistence, RemoteMemoryWorkPersistence {
+    supportsRealtimeChanges?: boolean;
     counts(): Promise<MemoryCounts>;
     temporal(window: {
         start: number;
@@ -11747,6 +11749,12 @@ interface RemoteMemoryStoreOptions {
     graphRanking?: RecallFactSource["graphRanking"];
     temporalRanking?: RecallFactSource["temporalRanking"];
     pollIntervalMs?: number;
+    activity?: {
+        isActive: () => boolean;
+        subscribe: (onChange: () => void) => () => void;
+    };
+    /** Report connection state on subscribe/reconnect and true on each account memory change. */
+    subscribeChanges?: (onChange: (connected: boolean) => void) => () => void;
 }
 declare class RemoteMemoryPartialCreateError extends Error {
     readonly created: StoredVaultMemory[];

package/dist/react/index.mjs

@@ -10287,11 +10287,12 @@ function isRemoteWorkLeaseExpired(error) {
 
 // src/lib/memory/store/remotePersistence.ts
 var RemoteMemoryError = class extends Error {
-  constructor(message, status, code, retryAfterMs) {
+  constructor(message, status, code, retryAfterMs, rateLimitBucket) {
     super(message);
     this.status = status;
     this.code = code;
     this.retryAfterMs = retryAfterMs;
+    this.rateLimitBucket = rateLimitBucket;
     this.name = "RemoteMemoryError";
   }
 };
@@ -10386,6 +10387,14 @@ function createNearbyRequest(options, apiPath = "/api/private-memories") {
     throw new Error("timeoutMs must be a positive number");
   const root = base.href.replace(/\/$/, "") + apiPath;
   const fetcher = options.fetch ?? globalThis.fetch;
+  const cooldowns = /* @__PURE__ */ new Map();
+  const memoryBudget = (path, method) => {
+    if (method === "PUT")
+      return path === "/topics" ? "private-memory-import" : "private-memory-write";
+    if (method === "POST" && ["/import", "/memories/batch", "/topics/import"].includes(path))
+      return "private-memory-import";
+    return "private-memory-read";
+  };
   const request = async (path, init = {}, signal) => {
     const controller = new AbortController();
     let timedOut = false;
@@ -10409,6 +10418,25 @@ function createNearbyRequest(options, apiPath = "/api/private-memories") {
       const token = await Promise.race([options.getToken(), aborted2]);
       if (controller.signal.aborted) await aborted2;
       if (!token) throw new RemoteMemoryError("Authentication required", 401);
+      const pathname = path.split("?")[0];
+      const route = `${init.method ?? "GET"} ${pathname}`;
+      const budgets = ["*", route];
+      if (apiPath === "/api/private-memories")
+        budgets.push("private-memory-ip", memoryBudget(pathname, init.method ?? "GET"));
+      for (const bucket of budgets) {
+        const cooldown = cooldowns.get(bucket);
+        if (!cooldown) continue;
+        const remaining = cooldown.until - Date.now();
+        if (remaining > 0)
+          throw new RemoteMemoryError(
+            cooldown.error.message,
+            429,
+            cooldown.error.code,
+            remaining,
+            cooldown.error.rateLimitBucket
+          );
+        cooldowns.delete(bucket);
+      }
       const response = await fetcher(root + path, {
         ...init,
         headers: {
@@ -10421,12 +10449,18 @@ function createNearbyRequest(options, apiPath = "/api/private-memories") {
       if (!response.ok) {
         const body = await response.json().catch(() => null);
         const retryAfter = parseRetryAfterMs(response.headers.get("Retry-After"));
-        throw new RemoteMemoryError(
+        const error = new RemoteMemoryError(
           record(body) && typeof body.detail === "string" ? body.detail : `Nearby request failed (${response.status})`,
           response.status,
           record(body) && typeof body.code === "string" ? body.code : void 0,
-          retryAfter ?? void 0
+          retryAfter ?? void 0,
+          record(body) && typeof body.rate_limit_bucket === "string" ? body.rate_limit_bucket : void 0
         );
+        if (response.status === 429 && retryAfter !== null && retryAfter > 0 && (!error.code || error.code === "rate_limited")) {
+          const bucket = error.rateLimitBucket && budgets.includes(error.rateLimitBucket) ? error.rateLimitBucket : record(body) && (body.limit_scope === "account" || body.limit_scope === "ip") && !error.rateLimitBucket ? "*" : route;
+          cooldowns.set(bucket, { until: Date.now() + retryAfter, error });
+        }
+        throw error;
       }
       return await response.json();
     } catch (error) {
@@ -10666,6 +10700,7 @@ async function createRemoteMemoryPersistence(options) {
   return {
     ...createRemoteTopicPersistence(request),
     ...createRemoteWorkPersistence(request),
+    supportsRealtimeChanges: account.realtime_changes === true,
     counts: async () => {
       const result = await request("/counts", {});
       if (!record(result) || ["live", "archived", "quarantined"].some(
@@ -23450,6 +23485,9 @@ var RemoteMemoryPartialCreateError = class extends Error {
 function rejectsInput(error) {
   return error instanceof EmbeddingHttpError && error.status !== void 0 && error.status >= 400 && error.status < 500 && error.status !== 429 && !isFatalEmbeddingError(error);
 }
+function rejectsMemoryWrite(error) {
+  return error instanceof RemoteMemoryError && (error.status === 400 || error.status === 422) && (error.code === void 0 || error.code === "unknown_field");
+}
 function warnFailed(failed) {
   if (failed.length)
     getLogger().warn(
@@ -23537,16 +23575,47 @@ function createRemoteMemoryStore(options) {
   const { persistence, embeddingOptions } = options;
   const model = embeddingOptions.model ?? DEFAULT_API_EMBEDDING_MODEL;
   const pollIntervalMs = options.pollIntervalMs ?? 6e4;
+  const activity = options.activity ?? {
+    isActive: () => (typeof document === "undefined" || document.visibilityState !== "hidden") && (typeof navigator === "undefined" || navigator.onLine !== false),
+    subscribe: (onChange) => {
+      if (typeof window === "undefined" || typeof document === "undefined") return () => {
+      };
+      document.addEventListener("visibilitychange", onChange);
+      window.addEventListener("online", onChange);
+      window.addEventListener("offline", onChange);
+      return () => {
+        document.removeEventListener("visibilitychange", onChange);
+        window.removeEventListener("online", onChange);
+        window.removeEventListener("offline", onChange);
+      };
+    }
+  };
   const pipeline = createRemoteMemoryPipeline({
     ...options,
     graphRanking: options.graphRanking ?? ((query, _traverse, recallOptions) => topicGraphRanking(query, recallOptions)),
     temporalRanking: options.temporalRanking ?? ((query, now) => eventTimeRanking(query, now))
   });
   const subscribers = /* @__PURE__ */ new Set();
+  const retainTopics = () => pollIntervalMs > 0 && [...subscribers].some((subscriber) => subscriber.options.topics);
   const seen = /* @__PURE__ */ new Map();
+  const reads = /* @__PURE__ */ new Map();
+  const metadataReads = /* @__PURE__ */ new Map();
+  let topicSnapshot;
+  let topicCatalog;
+  const invalidateReads = () => {
+    reads.clear();
+    metadataReads.clear();
+    topicSnapshot = void 0;
+    topicCatalog = void 0;
+  };
   let timer;
+  let scheduledAt;
+  let stopActivity;
+  let stopChanges;
+  let changesConnected = false;
   const notify = (change, records = []) => {
-    if (timer)
+    invalidateReads();
+    if (subscribers.size)
       for (const record2 of records) {
         const previous = seen.get(record2.memory.memory_id);
         if ((previous?.version ?? 0) + 1 === record2.version)
@@ -23570,8 +23639,37 @@ function createRemoteMemoryStore(options) {
     } while (cursor2 && records.length < max);
     return records.slice(0, max);
   };
-  const decrypted = (options2) => persistence.query(options2);
-  const metadata3 = (options2) => persistence.queryMetadata(options2);
+  const shareRead = (inflight, options2, read) => {
+    if (options2.signal) return read();
+    const key = JSON.stringify(Object.entries(options2).sort(([a], [b]) => a.localeCompare(b)));
+    const active = inflight.get(key);
+    if (active) return active;
+    const pending2 = read();
+    inflight.set(key, pending2);
+    const clear = () => {
+      if (inflight.get(key) === pending2) inflight.delete(key);
+    };
+    void pending2.then(clear, clear);
+    return pending2;
+  };
+  const decrypted = (options2) => shareRead(reads, options2, () => persistence.query(options2));
+  const metadata3 = (options2) => shareRead(
+    metadataReads,
+    options2,
+    () => persistence.queryMetadata(options2)
+  );
+  const readTopics = () => {
+    if (topicCatalog) return topicCatalog;
+    const pending2 = persistence.topics();
+    topicCatalog = pending2;
+    const clear = () => {
+      if (topicCatalog === pending2) topicCatalog = void 0;
+    };
+    void pending2.then(() => {
+      if (!retainTopics()) clear();
+    }, clear);
+    return pending2;
+  };
   const enumerate = (filters, max = Infinity) => pages(decrypted, filters, max);
   const memoriesByTopics = async (names) => {
     const wanted = new Set(names.map(normalizeEntityName).filter(Boolean));
@@ -24025,11 +24123,11 @@ function createRemoteMemoryStore(options) {
   };
   const changesSince = async (cursor2, pending2) => {
     const records = [];
-    const failed = /* @__PURE__ */ new Set();
+    const failed = /* @__PURE__ */ new Map();
     const collect = (page) => {
       warnFailed(page.failed);
       records.push(...page.items);
-      for (const failure of page.failed) failed.add(failure.memory_id);
+      for (const failure of page.failed) failed.set(failure.memory_id, failure.version);
     };
     let resume = cursor2;
     let next;
@@ -24063,25 +24161,72 @@ function createRemoteMemoryStore(options) {
   let ready = false;
   let cursor;
   let pending = /* @__PURE__ */ new Set();
+  let failedVersions = /* @__PURE__ */ new Map();
   let topicFingerprint;
   let polling = false;
+  let pollRequested = false;
+  let failures = 0;
+  let retryAt = 0;
+  const backoff = (error) => {
+    failures++;
+    retryAt = Date.now() + Math.max(
+      error instanceof RemoteMemoryError ? error.retryAfterMs ?? 0 : 0,
+      Math.min(pollIntervalMs * 2 ** Math.min(failures - 1, 10), 15 * 6e4)
+    );
+  };
+  const schedulePoll = (delay, keepEarlier = false) => {
+    const at = Math.max(Date.now() + delay, retryAt);
+    if (keepEarlier && timer && scheduledAt !== void 0 && scheduledAt <= at) return;
+    if (timer) clearTimeout(timer);
+    timer = void 0;
+    scheduledAt = void 0;
+    if (!subscribers.size || pollIntervalMs <= 0 || !activity.isActive()) return;
+    scheduledAt = at;
+    timer = setTimeout(poll, Math.max(0, at - Date.now()));
+  };
   const poll = () => {
-    if (polling) return;
+    if (timer) clearTimeout(timer);
+    timer = void 0;
+    scheduledAt = void 0;
+    if (!subscribers.size || pollIntervalMs <= 0 || !activity.isActive()) return;
+    if (Date.now() < retryAt) {
+      schedulePoll(0);
+      return;
+    }
+    if (polling) {
+      pollRequested = true;
+      return;
+    }
     polling = true;
+    pollRequested = false;
     const current = generation;
     changesSince(cursor, pending).then(async ({ records, resume, failed }) => {
       let topicState;
+      let topicFailed = false;
       if ([...subscribers].some((s) => s.options.topics))
         try {
-          topicState = JSON.stringify(
-            (await persistence.topics()).map((t) => [t.name, t.version])
-          );
+          topicCatalog = void 0;
+          topicState = JSON.stringify((await readTopics()).map((t) => [t.name, t.version]));
         } catch (error) {
+          topicFailed = true;
+          if (current === generation) backoff(error);
           getLogger().warn("[memory/remote-store] Topic subscription poll failed:", error);
         }
       if (current !== generation) return;
+      if (!topicFailed) {
+        failures = 0;
+        retryAt = 0;
+      }
+      const failedChanged = [...failed].some(
+        ([id2, version]) => failedVersions.get(id2) !== version
+      );
+      if (records.length || failedChanged || topicState !== void 0 && topicState !== topicFingerprint) {
+        reads.clear();
+        metadataReads.clear();
+        topicSnapshot = void 0;
+      }
       const changed = /* @__PURE__ */ new Set();
-      if (topicState !== void 0 && topicFingerprint !== void 0 && topicState !== topicFingerprint) {
+      if (ready && failedChanged || topicState !== void 0 && topicFingerprint !== void 0 && topicState !== topicFingerprint) {
         for (const subscriber of subscribers)
           if (subscriber.options.topics) changed.add(subscriber);
       }
@@ -24098,15 +24243,40 @@ function createRemoteMemoryStore(options) {
       }
       ready = true;
       cursor = resume;
-      pending = failed;
+      pending = new Set(failed.keys());
+      failedVersions = failed;
       for (const subscriber of changed)
         if (subscribers.has(subscriber)) safely(subscriber.onChange);
     }).catch((error) => {
+      if (current === generation) backoff(error);
       getLogger().warn("[memory/remote-store] Subscription poll failed:", error);
     }).finally(() => {
       polling = false;
+      schedulePoll(
+        current !== generation ? 0 : pollRequested ? 200 : changesConnected ? Math.max(pollIntervalMs, 5 * 6e4) : pollIntervalMs
+      );
     });
   };
+  const refreshActivity = () => {
+    if (timer) clearTimeout(timer);
+    timer = void 0;
+    if (!activity.isActive()) {
+      stopChanges?.();
+      stopChanges = void 0;
+      changesConnected = false;
+      return;
+    }
+    if (!stopChanges && persistence.supportsRealtimeChanges && options.subscribeChanges)
+      stopChanges = options.subscribeChanges((connected) => {
+        changesConnected = connected;
+        if (polling) {
+          pollRequested = true;
+          return;
+        }
+        schedulePoll(connected ? 200 : 0, true);
+      });
+    poll();
+  };
   const unrepairable = /* @__PURE__ */ new Set();
   let repairCursor;
   const repairEmbeddingsUnlocked = async ({
@@ -24162,40 +24332,78 @@ function createRemoteMemoryStore(options) {
       result.failed += targets.length;
       return finish();
     }
-    for (const [i, record2] of targets.entries()) {
+    const writes = targets.flatMap((record2, i) => {
       const vector = vectors[i];
       if (!vector) {
         result.failed++;
-        continue;
+        return [];
       }
-      await serialized(record2.memory.memory_id, async () => {
-        signal?.throwIfAborted();
-        try {
-          const [saved] = await persistence.putMany(
-            [
-              {
-                memory: {
-                  ...record2.memory,
-                  embedding: storedVector(vector),
-                  embedding_model: model
-                },
-                expectedVersion: record2
-              }
-            ],
-            signal,
-            leaseToken
-          );
-          notify("embedding", [saved]);
-          repaired.add(record2.memory.memory_id);
-          result.reembedded++;
-        } catch (error) {
+      try {
+        return [
+          {
+            memory: {
+              ...record2.memory,
+              embedding: storedVector(vector),
+              embedding_model: model
+            },
+            expectedVersion: record2
+          }
+        ];
+      } catch {
+        result.failed++;
+        return [];
+      }
+    });
+    for (const batch of chunks2(writes, MAX_BATCH)) {
+      const continueRepair = await serializedAll(
+        batch.map(({ memory }) => memory.memory_id),
+        async () => {
           signal?.throwIfAborted();
-          if (isRemoteWorkLeaseExpired(error)) throw error;
-          if (error instanceof RemoteMemoryError && error.code === "version_conflict")
-            result.skippedConflict++;
-          else result.failed++;
+          const commit = async (slice) => {
+            const saved = await persistence.putMany(slice, signal, leaseToken);
+            for (const record2 of saved) repaired.add(record2.memory.memory_id);
+            result.reembedded += saved.length;
+            notify("embedding", saved);
+          };
+          try {
+            await commit(batch);
+          } catch (error) {
+            signal?.throwIfAborted();
+            if (isRemoteWorkLeaseExpired(error)) throw error;
+            if (!(error instanceof RemoteMemoryError && error.code === "version_conflict") && !rejectsMemoryWrite(error)) {
+              result.failed += batch.length;
+              return false;
+            }
+            if (batch.length === 1) {
+              if (rejectsMemoryWrite(error)) {
+                unrepairable.add(batch[0].memory.memory_id);
+                result.failed++;
+              } else result.skippedConflict++;
+              return true;
+            }
+            for (const [index, write] of batch.entries()) {
+              signal?.throwIfAborted();
+              try {
+                await commit([write]);
+              } catch (error2) {
+                signal?.throwIfAborted();
+                if (isRemoteWorkLeaseExpired(error2)) throw error2;
+                if (error2 instanceof RemoteMemoryError && error2.code === "version_conflict")
+                  result.skippedConflict++;
+                else if (rejectsMemoryWrite(error2)) {
+                  unrepairable.add(write.memory.memory_id);
+                  result.failed++;
+                } else {
+                  result.failed += batch.length - index;
+                  return false;
+                }
+              }
+            }
+          }
+          return true;
         }
-      });
+      );
+      if (!continueRepair) break;
     }
     return finish();
   };
@@ -24235,7 +24443,7 @@ function createRemoteMemoryStore(options) {
     },
     importTopics: async (topics) => {
       if (!topics.length) return;
-      const existing = new Set((await persistence.topics()).map((topic2) => topic2.name));
+      const existing = new Set((await readTopics()).map((topic2) => topic2.name));
       const missing = topics.flatMap((topic2) => {
         const name = normalizeEntityName(topic2.name);
         if (existing.has(name)) return [];
@@ -24244,6 +24452,7 @@ function createRemoteMemoryStore(options) {
       });
       if (!missing.length) return;
       await persistence.importTopics(missing);
+      invalidateReads();
       for (const subscriber of [...subscribers])
         if (subscriber.options.topics) safely(subscriber.onChange);
     },
@@ -24257,40 +24466,51 @@ function createRemoteMemoryStore(options) {
     listProjections: async (listOptions = {}) => (await listRows(metadata3, listOptions, listFilters(listOptions), maxOf(listOptions))).map(
       projection
     ),
-    listTopics: async () => {
-      const topics = /* @__PURE__ */ new Map();
-      for (const { memory } of await pages(metadata3, {
-        include_archived: true,
-        include_quarantined: true,
-        include_superseded: true
-      })) {
-        for (const topic2 of parseTopics(memory.topics) ?? []) {
-          const name = normalizeEntityName(topic2.name);
-          if (!name) continue;
-          const entry = topics.get(name) ?? {
-            name,
-            kind: null,
-            memoryCount: 0,
-            members: /* @__PURE__ */ new Set()
-          };
-          entry.kind ?? (entry.kind = topic2.kind ?? null);
-          entry.members.add(memory.memory_id);
-          topics.set(name, entry);
-        }
-      }
-      for (const topic2 of await persistence.topics()) {
-        if (topic2.is_deleted) continue;
-        const current = topics.get(topic2.name);
-        if (current) current.kind ?? (current.kind = topic2.kind ?? null);
-        else
-          topics.set(topic2.name, {
-            name: topic2.name,
-            kind: topic2.kind ?? null,
-            memoryCount: 0,
-            members: /* @__PURE__ */ new Set()
-          });
-      }
-      return [...topics.values()].map(({ members, ...topic2 }) => ({ ...topic2, memoryCount: members.size })).sort((a, b) => a.name.localeCompare(b.name));
+    listTopics: () => {
+      if (topicSnapshot) return topicSnapshot.then((topics) => structuredClone(topics));
+      const snapshot = (async () => {
+        const topics = /* @__PURE__ */ new Map();
+        for (const { memory } of await pages(metadata3, {
+          include_archived: true,
+          include_quarantined: true,
+          include_superseded: true
+        })) {
+          for (const topic2 of parseTopics(memory.topics) ?? []) {
+            const name = normalizeEntityName(topic2.name);
+            if (!name) continue;
+            const entry = topics.get(name) ?? {
+              name,
+              kind: null,
+              memoryCount: 0,
+              members: /* @__PURE__ */ new Set()
+            };
+            entry.kind ?? (entry.kind = topic2.kind ?? null);
+            entry.members.add(memory.memory_id);
+            topics.set(name, entry);
+          }
+        }
+        for (const topic2 of await readTopics()) {
+          if (topic2.is_deleted) continue;
+          const current = topics.get(topic2.name);
+          if (current) current.kind ?? (current.kind = topic2.kind ?? null);
+          else
+            topics.set(topic2.name, {
+              name: topic2.name,
+              kind: topic2.kind ?? null,
+              memoryCount: 0,
+              members: /* @__PURE__ */ new Set()
+            });
+        }
+        return [...topics.values()].map(({ members, ...topic2 }) => ({ ...topic2, memoryCount: members.size })).sort((a, b) => a.name.localeCompare(b.name));
+      })();
+      topicSnapshot = snapshot;
+      const clear = () => {
+        if (topicSnapshot === snapshot) topicSnapshot = void 0;
+      };
+      void snapshot.then(() => {
+        if (!retainTopics()) clear();
+      }, clear);
+      return snapshot.then((topics) => structuredClone(topics));
     },
     get: async (id2) => asStored(await live(id2)),
     listArchived: async () => (await enumerate({ archived_only: true, order: "archived", include_embeddings: true })).map(
@@ -24471,20 +24691,23 @@ function createRemoteMemoryStore(options) {
     subscribe: (onChange, subscribeOptions = {}) => {
       const subscriber = { onChange, options: subscribeOptions };
       subscribers.add(subscriber);
-      if (pollIntervalMs > 0 && !timer) {
-        timer = setInterval(poll, pollIntervalMs);
-        poll();
+      if (pollIntervalMs > 0 && subscribers.size === 1) {
+        stopActivity = activity.subscribe(refreshActivity);
+        refreshActivity();
       }
       return () => {
         subscribers.delete(subscriber);
-        if (subscribers.size || !timer) return;
-        clearInterval(timer);
+        if (!retainTopics()) invalidateReads();
+        if (subscribers.size) return;
+        if (timer) clearTimeout(timer);
         timer = void 0;
+        stopActivity?.();
+        stopActivity = void 0;
+        stopChanges?.();
+        stopChanges = void 0;
+        changesConnected = false;
         generation++;
-        seen.clear();
-        ready = false;
-        cursor = void 0;
-        pending = /* @__PURE__ */ new Set();
+        invalidateReads();
       };
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anuma/sdk",
-  "version": "9.1.0",
+  "version": "9.1.1",
   "description": "",
   "main": "./dist/index.cjs",
   "module": "./dist/index.mjs",