memorysync-sdk 1.1.1 → 1.2.0

package/dist/index.mjs

@@ -467,7 +467,7 @@ var ControlPlaneClient = class {
 };
 
 // src/index.ts
-var SDK_VERSION2 = "1.1.0";
+var SDK_VERSION2 = "1.2.0";
 function camelToSnakeKey(key) {
   return key.replace(/([A-Z])/g, "_$1").toLowerCase();
 }
@@ -496,6 +496,22 @@ function snakeToCamelMemory(m) {
     score: m.score ?? null
   };
 }
+function buildQuery(params) {
+  if (!params) return "";
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0 || value === null) continue;
+    if (Array.isArray(value)) {
+      for (const item of value) {
+        if (item !== void 0 && item !== null) search.append(key, String(item));
+      }
+    } else {
+      search.append(key, String(value));
+    }
+  }
+  const qs = search.toString();
+  return qs ? `?${qs}` : "";
+}
 function safeJson2(text) {
   try {
     return JSON.parse(text);
@@ -555,17 +571,20 @@ var MemorySyncClient = class {
     return h;
   }
   async request(method, path, options = {}) {
-    const url = `${this.baseUrl}${path}`;
+    const url = `${this.baseUrl}${path}${buildQuery(options.query)}`;
     const controller = new AbortController();
     const timer = setTimeout(() => controller.abort(), this.timeoutMs);
     try {
       const headers = this.headers(
         options.endUserOverride ? { "X-End-User-ID": options.endUserOverride } : {}
       );
+      if (options.form) {
+        delete headers["Content-Type"];
+      }
       const res = await this.fetchImpl(url, {
         method,
         headers,
-        body: options.body !== void 0 ? JSON.stringify(options.body) : void 0,
+        body: options.form ? options.form : options.body !== void 0 ? JSON.stringify(options.body) : void 0,
         signal: controller.signal
       });
       const requestId = res.headers.get("X-Request-ID") ?? void 0;
@@ -692,14 +711,51 @@ var MemorySyncClient = class {
     const raw = await this.request("PATCH", `/memory/${memoryId}`, { body });
     return snakeToCamelMemory(raw);
   }
-  async forget(memoryIds, reason) {
-    if (!Array.isArray(memoryIds) || memoryIds.length === 0) {
-      throw new ValidationError("memoryIds must be a non-empty array");
+  async forget(arg, legacyReason) {
+    const req = Array.isArray(arg) ? { memoryIds: arg, reason: legacyReason } : arg;
+    const hasIds = req.memoryIds !== void 0;
+    const hasFilters = req.filters !== void 0;
+    if (hasIds && hasFilters) {
+      throw new ValidationError("Provide either memoryIds or filters, not both");
+    }
+    if (!hasIds && !hasFilters) {
+      throw new ValidationError("Provide either memoryIds or filters");
     }
-    const body = { memory_ids: memoryIds };
-    if (reason !== void 0) body.reason = reason;
+    const body = {};
+    if (hasIds) {
+      if (!Array.isArray(req.memoryIds) || req.memoryIds.length === 0) {
+        throw new ValidationError("memoryIds must be a non-empty array");
+      }
+      body.memory_ids = req.memoryIds;
+    } else {
+      const f = req.filters;
+      const filters = {};
+      if (f.source !== void 0) filters.source = f.source;
+      if (f.eventType !== void 0) filters.event_type = f.eventType;
+      if (f.tags !== void 0) filters.tags = f.tags;
+      if (f.tier !== void 0) filters.tier = f.tier;
+      if (f.before !== void 0) filters.before = f.before;
+      if (f.after !== void 0) filters.after = f.after;
+      if (Object.keys(filters).length === 0) {
+        throw new ValidationError(
+          "filters must set at least one criterion; use purgeUser() to remove everything for an end user"
+        );
+      }
+      body.filters = filters;
+      if (req.dryRun) body.dry_run = true;
+    }
+    if (req.reason !== void 0) body.reason = req.reason;
     return await this.request("DELETE", "/memory/forget", { body });
   }
+  /**
+   * Delete every memory belonging to the calling end user.
+   *
+   * Separate from {@link forget} on purpose: this reads like what it does, so a
+   * whole-namespace delete can never be the accidental result of an empty filter.
+   */
+  async purgeUser() {
+    return await this.request("DELETE", "/memory/user/purge") ?? {};
+  }
   async summarize(req) {
     if (!req.memoryIds || req.memoryIds.length === 0) {
       throw new ValidationError("summarize() requires memoryIds");
@@ -757,7 +813,351 @@ var MemorySyncClient = class {
       createdAt: raw.created_at
     };
   }
+  // ── Files ──────────────────────────────────────────────────────────
+  /**
+   * Ingest a document and store the memories extracted from its text.
+   *
+   * Accepts the formats the connectors accept — PDF, DOCX, PPTX, XLSX, CSV,
+   * text, Markdown, HTML, source code, and images/audio/video where
+   * transcription is configured.
+   *
+   * Billed as an add, one unit per memory created. Resolves to the first stored
+   * memory, or an {@link AddSkippedResponse} when the file yielded nothing worth
+   * keeping — a blank scan, a sheet of empty cells, or content the extractor
+   * judges trivial are all normal outcomes rather than errors.
+   */
+  async upload(req) {
+    if (!req.filename?.trim()) {
+      throw new ValidationError("filename is required so the server can pick a parser");
+    }
+    const form = new FormData();
+    const blob = req.file instanceof Uint8Array ? new Blob([req.file], {
+      type: req.contentType ?? "application/octet-stream"
+    }) : req.file;
+    form.append("file", blob, req.filename);
+    if (req.source !== void 0) form.append("source", req.source);
+    if (req.metadata !== void 0) form.append("metadata", JSON.stringify(req.metadata));
+    if (req.endUserId !== void 0) form.append("end_user_id", req.endUserId);
+    const raw = await this.request("POST", "/memory/upload", {
+      form,
+      endUserOverride: req.endUserId
+    });
+    if (raw && raw.status === "skipped") {
+      return {
+        status: "skipped",
+        reason: raw.reason ?? "no_extractable_text",
+        memoryIds: raw.memory_ids ?? [],
+        candidatesExtracted: raw.candidates_extracted ?? 0,
+        candidatesStored: raw.candidates_stored ?? 0
+      };
+    }
+    return snakeToCamelMemory(raw);
+  }
+  // ── Bulk edit ──────────────────────────────────────────────────────
+  /**
+   * Apply many metadata edits in one request.
+   *
+   * Editable: `tags`, `importance`, `metadata`, `source`, `eventType`. A memory's
+   * text, embeddings, owner, environment and project are not editable.
+   *
+   * Applied in one transaction, so the batch either lands or it does not — but an
+   * id the caller cannot see is reported per item rather than failing the request.
+   */
+  async batchUpdate(items) {
+    if (!Array.isArray(items) || items.length === 0) {
+      throw new ValidationError("items must contain at least one entry");
+    }
+    if (items.length > 100) {
+      throw new ValidationError("items may contain at most 100 entries per request");
+    }
+    const seen = /* @__PURE__ */ new Map();
+    const payload = items.map((item, index) => {
+      if (!Number.isInteger(item.memoryId) || item.memoryId <= 0) {
+        throw new ValidationError(`items[${index}].memoryId must be a positive integer`);
+      }
+      const o = { memory_id: item.memoryId };
+      if (item.tags !== void 0) o.tags = item.tags;
+      if (item.importance !== void 0) o.importance = item.importance;
+      if (item.metadata !== void 0) o.metadata = item.metadata;
+      if (item.source !== void 0) o.source = item.source;
+      if (item.eventType !== void 0) o.event_type = item.eventType;
+      if (Object.keys(o).length === 1) {
+        throw new ValidationError(
+          `items[${index}] (memoryId ${item.memoryId}): at least one updatable field must be provided`
+        );
+      }
+      const previous = seen.get(item.memoryId);
+      if (previous !== void 0) {
+        throw new ValidationError(
+          `items must not contain the same memoryId twice: ${item.memoryId} appears at index ${previous} and ${index}`
+        );
+      }
+      seen.set(item.memoryId, index);
+      return o;
+    });
+    const raw = await this.request("POST", "/memory/batch-update", {
+      body: { items: payload }
+    });
+    return {
+      total: raw?.total ?? 0,
+      updated: raw?.updated ?? 0,
+      notFound: raw?.not_found ?? 0,
+      results: (raw?.results ?? []).map((r) => ({
+        index: r.index,
+        memoryId: r.memory_id,
+        status: r.status,
+        changedFields: r.changed_fields ?? []
+      }))
+    };
+  }
+  // ── History and feedback ───────────────────────────────────────────
+  /**
+   * Recorded changes to one memory, oldest first.
+   *
+   * Entry 0 is the creation. Later entries carry the old and new value per field.
+   * Entries written by background workers have `actor: null`. Only
+   * user-meaningful fields are tracked; the watched list comes back in
+   * `trackedFields`.
+   */
+  async history(memoryId, opts = {}) {
+    if (!Number.isInteger(memoryId) || memoryId <= 0) {
+      throw new ValidationError("memoryId must be a positive integer");
+    }
+    const raw = await this.request(
+      "GET",
+      `/memory/${memoryId}/history`,
+      { query: { limit: opts.limit ?? 100, offset: opts.offset ?? 0 } }
+    );
+    return {
+      memoryId: raw?.memory_id ?? memoryId,
+      total: raw?.total ?? 0,
+      revisions: (raw?.revisions ?? []).map((r) => ({
+        revision: r.revision,
+        event: r.event,
+        changedFields: r.changed_fields ?? [],
+        diff: r.diff ?? {},
+        actor: r.actor ?? null,
+        createdAt: r.created_at
+      })),
+      trackedFields: raw?.tracked_fields ?? []
+    };
+  }
+  /**
+   * Tell MemorySync whether a memory was useful.
+   *
+   * By default this moves the memory's `importance`, a weighted retrieval-ranking
+   * factor, so a memory marked useful surfaces more readily and one marked wrong
+   * surfaces less. The size of the move is adaptive: consistent signals amplify
+   * it, mixed signals damp it. Importance is clamped to [0.05, 1.0], so no run of
+   * negative feedback can make a memory permanently unreachable. Not billed.
+   */
+  async feedback(memoryId, signal, opts = {}) {
+    if (!Number.isInteger(memoryId) || memoryId <= 0) {
+      throw new ValidationError("memoryId must be a positive integer");
+    }
+    const valid = ["positive", "negative", "retrieved", "ignored"];
+    if (!valid.includes(signal)) {
+      throw new ValidationError(`signal must be one of ${valid.join(", ")}; got ${String(signal)}`);
+    }
+    const body = { signal };
+    if (opts.comment !== void 0) body.comment = opts.comment;
+    const raw = await this.request(
+      "POST",
+      `/memory/${memoryId}/feedback`,
+      { body }
+    );
+    const summary = raw?.summary ?? {};
+    const trend = summary.trend ?? {};
+    return {
+      memoryId: raw?.memory_id ?? memoryId,
+      signal: raw?.signal ?? signal,
+      importanceBefore: raw?.importance_before ?? 0,
+      importanceAfter: raw?.importance_after ?? 0,
+      adjustment: raw?.adjustment ?? 0,
+      influencedRanking: Boolean(raw?.influenced_ranking),
+      summary: {
+        totalSignals: summary.total_signals ?? 0,
+        signalCounts: summary.signal_counts ?? {},
+        trend: {
+          momentum: trend.momentum ?? "neutral",
+          consistency: trend.consistency ?? 0,
+          trendMultiplier: trend.trend_multiplier ?? 1,
+          recentCount: trend.recent_count ?? 0
+        }
+      }
+    };
+  }
+  // ── Ontology ───────────────────────────────────────────────────────
+  /** The memory vocabulary in effect for this organization. */
+  async getOntology() {
+    const raw = await this.request("GET", "/memory/ontology");
+    return toOntology(raw);
+  }
+  /**
+   * Replace this organization's *additions* to the vocabulary.
+   *
+   * The two vocabularies are independent: omit one and it is left untouched, so
+   * adding a content type cannot wipe your relation types. Pass an empty array to
+   * clear a vocabulary's custom entries. The built-in types always remain.
+   */
+  async updateOntology(req) {
+    if (req.contentTypes === void 0 && req.relationTypes === void 0) {
+      throw new ValidationError(
+        "provide contentTypes, relationTypes, or both; an empty request would silently do nothing"
+      );
+    }
+    const body = {};
+    if (req.contentTypes !== void 0) body.content_types = req.contentTypes;
+    if (req.relationTypes !== void 0) body.relation_types = req.relationTypes;
+    const raw = await this.request("PUT", "/memory/ontology", { body });
+    return toOntology(raw);
+  }
+  // ── Retrieval variants ─────────────────────────────────────────────
+  /**
+   * Alias of {@link query} against `/memory/retrieve`.
+   *
+   * Both paths are live, and integrators arriving from other platforms reach for
+   * `retrieve`. Identical semantics.
+   */
+  async retrieve(req) {
+    const body = { query: req.query };
+    if (req.k !== void 0) body.k = req.k;
+    if (req.filters !== void 0) body.filters = camelToSnakeShallow(req.filters);
+    if (req.sessionId !== void 0) body.session_id = req.sessionId;
+    if (req.traversalDepth !== void 0) body.traversal_depth = req.traversalDepth;
+    const raw = await this.request("POST", "/memory/retrieve", { body });
+    return {
+      memories: (raw.memories ?? []).map(snakeToCamelMemory),
+      context: raw.context ?? null,
+      latencyMs: raw.latency_ms ?? null,
+      sessionId: raw.session_id ?? null,
+      queryIntent: raw.query_intent ?? null
+    };
+  }
+  /**
+   * Route a question to the best knowledge source and answer from it.
+   *
+   * Returns the raw payload: the response carries routing diagnostics whose shape
+   * is richer and more volatile than an SDK should freeze into an interface.
+   */
+  async searchRouted(query, opts = {}) {
+    const body = { query };
+    if (opts.k !== void 0) body.k = opts.k;
+    if (opts.route !== void 0) body.route = opts.route;
+    if (opts.includeReasoning !== void 0) body.include_reasoning = opts.includeReasoning;
+    return await this.request("POST", "/memory/search/routed", { body }) ?? {};
+  }
+  /** Compose an answer across several memories, with citations. */
+  async synthesize(opts = {}) {
+    const body = {};
+    if (opts.query !== void 0) body.query = opts.query;
+    if (opts.memoryIds !== void 0) body.memory_ids = opts.memoryIds;
+    if (opts.maxMemories !== void 0) body.max_memories = opts.maxMemories;
+    return await this.request("POST", "/memory/synthesize", { body }) ?? {};
+  }
+  /** Re-embed this end user's memories. Returns immediately (`202`). */
+  async refresh() {
+    return await this.request("POST", "/memory/refresh") ?? {};
+  }
+  // ── Intelligence and graph ─────────────────────────────────────────
+  /** Nodes and typed edges for this end user's memory graph. */
+  async graph(opts = {}) {
+    return await this.request("GET", "/memory/graph", {
+      query: { limit: opts.limit, memory_id: opts.memoryId, depth: opts.depth }
+    }) ?? {};
+  }
+  /** Semantic clusters over this end user's memories. */
+  async clusters(opts = {}) {
+    return await this.request("GET", "/memory/clusters", {
+      query: { limit: opts.limit }
+    }) ?? {};
+  }
+  /** Contradictions and open decisions detected across memories. */
+  async decisions(opts = {}) {
+    return await this.request("GET", "/memory/decisions", {
+      query: { limit: opts.limit }
+    }) ?? {};
+  }
+  /** Record which side of a contradiction wins. */
+  async resolveDecision(opts = {}) {
+    const body = {};
+    if (opts.decisionId !== void 0) body.decision_id = opts.decisionId;
+    if (opts.winningMemoryId !== void 0) body.winning_memory_id = opts.winningMemoryId;
+    if (opts.resolution !== void 0) body.resolution = opts.resolution;
+    if (opts.note !== void 0) body.note = opts.note;
+    return await this.request("POST", "/memory/decision/resolve", { body }) ?? {};
+  }
+  /**
+   * The intelligence report: themes, entities, patterns, dual-horizon view.
+   *
+   * `scope` is explicit by design server-side — nothing is inferred, so if you do
+   * not ask for a scope you do not get it.
+   */
+  async intelligence(opts = {}) {
+    return await this.request("GET", "/memory/intelligence", {
+      query: { limit: opts.limit, scope: opts.scope, project_id: opts.projectId }
+    }) ?? {};
+  }
+  /** Counts and coverage for the knowledge base. */
+  async knowledgeStats() {
+    return await this.request("GET", "/memory/knowledge/stats") ?? {};
+  }
+  // ── v1 data plane ──────────────────────────────────────────────────
+  /** Add a conversation turn and extract memories from it. */
+  async addTurn(req) {
+    const body = {
+      tenant_id: req.tenantId,
+      user_id: req.userId,
+      messages: req.messages
+    };
+    if (req.sessionId !== void 0) body.session_id = req.sessionId;
+    if (req.metadata !== void 0) body.metadata = req.metadata;
+    return await this.request("POST", "/v1/memory/add_turn", { body }) ?? {};
+  }
+  /**
+   * Build a prompt-ready context block for an LLM call.
+   *
+   * `types` narrows the result to those content types. Names outside the
+   * organization's vocabulary are dropped rather than rejected, so a stale client
+   * gets a narrower answer instead of an error.
+   */
+  async recall(req) {
+    const body = {
+      tenant_id: req.tenantId,
+      user_id: req.userId,
+      prompt: req.prompt
+    };
+    if (req.k !== void 0) body.k = req.k;
+    if (req.types !== void 0) body.types = req.types;
+    return await this.request("POST", "/v1/memory/recall", { body }) ?? {};
+  }
+  /** Async ingestion status for one memory. */
+  async status(memoryId) {
+    if (!Number.isInteger(memoryId) || memoryId <= 0) {
+      throw new ValidationError("memoryId must be a positive integer");
+    }
+    return await this.request("GET", `/v1/memory/status/${memoryId}`) ?? {};
+  }
+  /** Page through a specific end user's memories. */
+  async listMemories(req) {
+    return await this.request(
+      "GET",
+      `/v1/memory/${encodeURIComponent(req.tenantId)}/${encodeURIComponent(req.userId)}/list`,
+      { query: { limit: req.limit, offset: req.offset } }
+    ) ?? {};
+  }
 };
+function toOntology(raw) {
+  return {
+    contentTypes: raw?.content_types ?? [],
+    relationTypes: raw?.relation_types ?? [],
+    builtinContentTypes: raw?.builtin_content_types ?? [],
+    builtinRelationTypes: raw?.builtin_relation_types ?? [],
+    customContentTypes: raw?.custom_content_types ?? [],
+    customRelationTypes: raw?.custom_relation_types ?? [],
+    maxCustomTypes: raw?.max_custom_types ?? 32
+  };
+}
 export {
   AuthError,
   ControlPlaneClient,