@persistmemory/sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1015 @@
+// src/query.ts
+function encodeQuery(params) {
+  if (!params) return "";
+  const search = new URLSearchParams();
+  for (const [key, value] of Object.entries(params)) {
+    if (value === void 0) continue;
+    if (Array.isArray(value)) {
+      for (const one of value) search.append(key, String(one));
+      continue;
+    }
+    search.append(key, String(value));
+  }
+  const encoded = search.toString();
+  return encoded ? `?${encoded}` : "";
+}
+function pageQuery(params, cursor, extra) {
+  return {
+    ...params.limit !== void 0 ? { limit: params.limit } : {},
+    ...cursor !== void 0 ? { cursor } : params.cursor !== void 0 ? { cursor: params.cursor } : {},
+    ...extra
+  };
+}
+
+// src/backoff.ts
+var DEFAULT_BACKOFF = { baseMs: 250, maxMs: 8e3, factor: 2, jitter: 1 };
+function backoffMs(attempt, options = {}) {
+  const base = options.baseMs ?? DEFAULT_BACKOFF.baseMs;
+  const max = options.maxMs ?? DEFAULT_BACKOFF.maxMs;
+  const factor = options.factor ?? DEFAULT_BACKOFF.factor;
+  const jitter = clamp01(options.jitter ?? DEFAULT_BACKOFF.jitter);
+  const random = options.random ?? Math.random;
+  const exponent = Math.max(0, Math.floor(attempt) - 1);
+  const ceiling = Math.min(max, base * Math.pow(factor, exponent));
+  if (jitter <= 0) return Math.round(ceiling);
+  const fixed = ceiling * (1 - jitter);
+  return Math.round(fixed + random() * (ceiling - fixed));
+}
+function delayFor(args) {
+  const computed = backoffMs(args.attempt, args.options ?? {});
+  if (args.retryAfterSeconds === void 0 || !Number.isFinite(args.retryAfterSeconds)) {
+    return computed;
+  }
+  return Math.max(computed, Math.max(0, args.retryAfterSeconds) * 1e3);
+}
+function clamp01(value) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(1, Math.max(0, value));
+}
+
+// src/errors.ts
+var PersistMemoryError = class extends Error {
+  status;
+  code;
+  fields;
+  requestId;
+  retryAfterSeconds;
+  /** Retrying this exact request could plausibly succeed. */
+  retryable = false;
+  constructor(init) {
+    super(redact(init.message));
+    this.name = new.target.name;
+    this.status = init.status;
+    this.code = init.code;
+    if (init.fields) this.fields = init.fields;
+    if (init.requestId) this.requestId = init.requestId;
+    if (init.retryAfterSeconds !== void 0) this.retryAfterSeconds = init.retryAfterSeconds;
+  }
+  /**
+   * A one-line summary safe to log.
+   *
+   * Provided so callers reach for this instead of `JSON.stringify(error)`,
+   * which walks own properties and would pick up anything a future field
+   * holds. Everything here is already server-supplied and key-free.
+   */
+  toString() {
+    const id = this.requestId ? ` requestId=${this.requestId}` : "";
+    return `${this.name}: [${this.status} ${this.code}] ${this.message}${id}`;
+  }
+};
+var AuthenticationError = class extends PersistMemoryError {
+};
+var PermissionDeniedError = class extends PersistMemoryError {
+};
+var NotFoundError = class extends PersistMemoryError {
+};
+var ValidationError = class extends PersistMemoryError {
+};
+var ConflictError = class extends PersistMemoryError {
+};
+var RateLimitError = class extends PersistMemoryError {
+  retryable = true;
+};
+var ServerError = class extends PersistMemoryError {
+  retryable = true;
+};
+var ConnectionError = class extends PersistMemoryError {
+  retryable = true;
+  constructor(message) {
+    super({ status: 0, code: "CONNECTION_ERROR", message });
+  }
+};
+var TimeoutError = class extends PersistMemoryError {
+  retryable = true;
+  constructor(message) {
+    super({ status: 0, code: "TIMEOUT", message });
+  }
+};
+var AbortError = class extends PersistMemoryError {
+  constructor(message = "The request was aborted by the caller.") {
+    super({ status: 0, code: "ABORTED", message });
+  }
+};
+function errorFromResponse(status, body, headers) {
+  const envelope = body ?? {};
+  const code = typeof envelope.error?.code === "string" ? envelope.error.code : codeForStatus(status);
+  const message = typeof envelope.error?.message === "string" && envelope.error.message.length > 0 ? envelope.error.message : defaultMessage(status);
+  const retryAfterSeconds = status === 429 || status === 503 ? retryAfterOf(headers) : void 0;
+  const init = {
+    status,
+    code,
+    message,
+    ...isFieldMap(envelope.error?.fields) ? { fields: envelope.error.fields } : {},
+    ...typeof envelope.error?.requestId === "string" ? { requestId: envelope.error.requestId } : {},
+    ...retryAfterSeconds !== void 0 ? { retryAfterSeconds } : {}
+  };
+  if (status === 429 || code === "RATE_LIMITED") return new RateLimitError(init);
+  if (status === 401 || code === "UNAUTHORIZED") return new AuthenticationError(init);
+  if (status === 403 || code === "FORBIDDEN") return new PermissionDeniedError(init);
+  if (status === 404 || code === "NOT_FOUND") return new NotFoundError(init);
+  if (status === 409 || code === "CONFLICT") return new ConflictError(init);
+  if (status === 400 || status === 413 || status === 422) return new ValidationError(init);
+  if (status >= 500) return new ServerError(init);
+  return new PersistMemoryError(init);
+}
+function retryAfterOf(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return void 0;
+  const seconds = Number(raw.trim());
+  if (!Number.isFinite(seconds) || seconds < 0) return void 0;
+  return Math.min(seconds, 300);
+}
+function isFieldMap(value) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  return Object.values(value).every((one) => typeof one === "string");
+}
+function codeForStatus(status) {
+  if (status === 401) return "UNAUTHORIZED";
+  if (status === 403) return "FORBIDDEN";
+  if (status === 404) return "NOT_FOUND";
+  if (status === 409) return "CONFLICT";
+  if (status === 429) return "RATE_LIMITED";
+  if (status === 413) return "PAYLOAD_TOO_LARGE";
+  if (status >= 500) return "INTERNAL_ERROR";
+  return "VALIDATION_ERROR";
+}
+function defaultMessage(status) {
+  return `The API returned ${status} with no readable error body.`;
+}
+function redact(text) {
+  return text.replace(/pm_(live|test)_[A-Za-z0-9_-]+/g, "pm_$1_[redacted]");
+}
+
+// src/http.ts
+var DEFAULT_BASE_URL = "https://api.persistmemory.com";
+var DEFAULT_TIMEOUT_MS = 3e4;
+var DEFAULT_MAX_ATTEMPTS = 3;
+var RETRY_WITHOUT_ASKING = /* @__PURE__ */ new Set(["GET", "HEAD", "PATCH", "DELETE"]);
+var HttpClient = class {
+  /**
+   * The credential, in a private field, and never anywhere else.
+   *
+   * Private (`#`) rather than `readonly`: a public field is enumerable, so
+   * `JSON.stringify(client)` and every structured logger that walks own
+   * properties would write the key into a log line. `toJSON` and the inspect
+   * hook below close the two remaining paths - a bug report pasted from
+   * `console.log(client)` is exactly how a key gets shared with strangers.
+   */
+  #apiKey;
+  #baseUrl;
+  #fetch;
+  #timeoutMs;
+  #maxAttempts;
+  #backoff;
+  #sleep;
+  #userAgent;
+  constructor(options) {
+    if (typeof options.apiKey !== "string" || options.apiKey.trim().length === 0) {
+      throw new PersistMemoryError({
+        status: 0,
+        code: "VALIDATION_ERROR",
+        message: "An API key is required. Pass `apiKey`, or set PERSISTMEMORY_API_KEY."
+      });
+    }
+    const key = options.apiKey.trim();
+    if (/[\r\n\0]/.test(key)) {
+      throw new PersistMemoryError({
+        status: 0,
+        code: "VALIDATION_ERROR",
+        message: "The API key contains characters that cannot go in a header."
+      });
+    }
+    this.#apiKey = key;
+    this.#baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.#fetch = options.fetch ?? globalThis.fetch;
+    this.#timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.#maxAttempts = Math.max(1, options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS);
+    this.#backoff = options.backoff ?? {};
+    this.#sleep = options.sleep ?? defaultSleep;
+    this.#userAgent = options.userAgent ?? "persistmemory-sdk-js/0.1.0";
+  }
+  /**
+   * What this object looks like when something serialises it.
+   *
+   * Both hooks return the same key-free shape. `toJSON` covers
+   * `JSON.stringify`, the inspect symbol covers `console.log` under Node, and
+   * between them they cover how a credential actually escapes: not through a
+   * deliberate log line, but through an object dumped into a bug report.
+   */
+  toJSON() {
+    return { baseUrl: this.#baseUrl, apiKey: "[redacted]" };
+  }
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.toJSON();
+  }
+  async get(path, query, options) {
+    return this.#request({
+      method: "GET",
+      path,
+      ...query ? { query } : {},
+      ...options ? { options } : {}
+    });
+  }
+  async post(path, body, options) {
+    return this.#request({
+      method: "POST",
+      path,
+      ...body !== void 0 ? { body } : {},
+      ...options ? { options } : {}
+    });
+  }
+  async patch(path, body, options) {
+    return this.#request({
+      method: "PATCH",
+      path,
+      ...body !== void 0 ? { body } : {},
+      ...options ? { options } : {}
+    });
+  }
+  async delete(path, body, options) {
+    return this.#request({
+      method: "DELETE",
+      path,
+      ...body !== void 0 ? { body } : {},
+      ...options ? { options } : {}
+    });
+  }
+  async #request(request) {
+    const maxAttempts = Math.max(1, request.options?.maxAttempts ?? this.#maxAttempts);
+    const url = this.#baseUrl + request.path + encodeQuery(request.query);
+    let attempt = 0;
+    for (; ; ) {
+      attempt += 1;
+      let error;
+      try {
+        return await this.#attempt(request, url);
+      } catch (thrown) {
+        if (!(thrown instanceof PersistMemoryError)) throw thrown;
+        error = thrown;
+      }
+      if (attempt >= maxAttempts) throw error;
+      if (!mayRetry(error, request)) throw error;
+      const delay = delayFor({
+        attempt,
+        ...error.retryAfterSeconds !== void 0 ? { retryAfterSeconds: error.retryAfterSeconds } : {},
+        options: this.#backoff
+      });
+      await this.#sleep(delay, request.options?.signal);
+    }
+  }
+  async #attempt(request, url) {
+    const timeoutMs = request.options?.timeoutMs ?? this.#timeoutMs;
+    const deadline = new AbortController();
+    const timer = setTimeout(() => deadline.abort(), timeoutMs);
+    const onCallerAbort = () => deadline.abort();
+    const caller = request.options?.signal;
+    caller?.addEventListener("abort", onCallerAbort, { once: true });
+    try {
+      if (caller?.aborted) throw new AbortError();
+      const response = await untilAborted(
+        this.#fetch(url, {
+          method: request.method,
+          headers: this.#headers(request),
+          ...request.body !== void 0 ? { body: JSON.stringify(request.body) } : {},
+          signal: deadline.signal
+        }),
+        deadline.signal
+      );
+      const payload = await readBody(response);
+      if (!response.ok) throw errorFromResponse(response.status, payload, response.headers);
+      return payload;
+    } catch (thrown) {
+      if (thrown instanceof PersistMemoryError) throw thrown;
+      if (caller?.aborted) throw new AbortError();
+      if (deadline.signal.aborted) {
+        throw new TimeoutError(`The request did not complete within ${timeoutMs}ms.`);
+      }
+      const detail = thrown instanceof Error ? redact(thrown.message) : "transport failure";
+      throw new ConnectionError(`Could not reach the API: ${detail}`);
+    } finally {
+      clearTimeout(timer);
+      caller?.removeEventListener("abort", onCallerAbort);
+    }
+  }
+  #headers(request) {
+    return {
+      // The only place the key is ever read.
+      authorization: `Bearer ${this.#apiKey}`,
+      accept: "application/json",
+      "user-agent": this.#userAgent,
+      ...request.body !== void 0 ? { "content-type": "application/json" } : {},
+      ...request.options?.idempotencyKey ? { "idempotency-key": request.options.idempotencyKey } : {}
+    };
+  }
+};
+function mayRetry(error, request) {
+  if (!error.retryable) return false;
+  if (RETRY_WITHOUT_ASKING.has(request.method)) return true;
+  if (request.options?.idempotencyKey) return true;
+  return error.status === 429;
+}
+async function readBody(response) {
+  if (response.status === 204) return void 0;
+  const text = await response.text().catch(() => "");
+  if (text.length === 0) return void 0;
+  const type = response.headers.get("content-type") ?? "";
+  if (!type.includes("json")) return { raw: text.slice(0, 500) };
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text.slice(0, 500) };
+  }
+}
+var SignalFired = class extends Error {
+  constructor() {
+    super("signal fired");
+    this.name = "SignalFired";
+  }
+};
+function untilAborted(work, signal) {
+  work.catch(() => void 0);
+  return new Promise((resolve, reject) => {
+    if (signal.aborted) {
+      reject(new SignalFired());
+      return;
+    }
+    const onAbort = () => reject(new SignalFired());
+    signal.addEventListener("abort", onAbort, { once: true });
+    work.then(
+      (value) => {
+        signal.removeEventListener("abort", onAbort);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener("abort", onAbort);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    );
+  });
+}
+function defaultSleep(ms, signal) {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new AbortError());
+      return;
+    }
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    function onAbort() {
+      clearTimeout(timer);
+      reject(new AbortError());
+    }
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+// src/pagination.ts
+var Paginated = class {
+  #fetchPage;
+  constructor(fetchPage) {
+    this.#fetchPage = fetchPage;
+  }
+  /** The first page, and nothing more. For a UI that renders one page at a time. */
+  async first() {
+    return this.#fetchPage(void 0);
+  }
+  /**
+   * Page by page, for a caller that wants the cursors or wants to stop early.
+   *
+   * A generator rather than an array of pages: fetching them all up front
+   * would make "show me the first ten" cost every page in the account.
+   */
+  async *pages() {
+    let cursor;
+    const seen = /* @__PURE__ */ new Set();
+    for (; ; ) {
+      const page = await this.#fetchPage(cursor);
+      yield page;
+      const next = page.pagination.nextCursor;
+      if (!next) return;
+      if (seen.has(next)) return;
+      seen.add(next);
+      cursor = next;
+    }
+  }
+  /** Every item across every page. `for await (const memory of ...)`. */
+  async *[Symbol.asyncIterator]() {
+    for await (const page of this.pages()) {
+      for (const item of page.data) yield item;
+    }
+  }
+  /**
+   * Everything, in one array.
+   *
+   * `maxItems` is not optional, and that is the point. An unbounded `all()` on
+   * an account with two hundred thousand memories is a request loop that runs
+   * for minutes and an array that exhausts the heap, and the call site that
+   * does it reads as innocently as any other. Ask for a number you can hold.
+   */
+  async all(maxItems) {
+    const collected = [];
+    if (maxItems <= 0) return collected;
+    for await (const item of this) {
+      collected.push(item);
+      if (collected.length >= maxItems) break;
+    }
+    return collected;
+  }
+};
+
+// src/resources/memories.ts
+var Memories = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * One page, plus the cursor loop.
+   *
+   * Returns a `Paginated`, so `await memories.list().first()` gets a page and
+   * `for await (const memory of memories.list())` walks the lot. The filters
+   * are carried into every page automatically - a caller re-passing them per
+   * page is a caller who will eventually forget one, and the pages after that
+   * come from a differently filtered list.
+   */
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/memories",
+        pageQuery(params, cursor, toQuery(params)),
+        options
+      )
+    );
+  }
+  async get(id, options) {
+    return this.#http.get(`/api/v1/memories/${encodeURIComponent(id)}`, void 0, options);
+  }
+  /**
+   * Hands material to the ingestion pipeline. Needs a key with `write` scope.
+   *
+   * This does NOT create a memory, and the return type says so: it answers 202
+   * with a job id. Extraction, entity resolution, deduplication and conflict
+   * detection all run afterwards and may produce one memory, several, or none.
+   * Poll `client.jobs.get(result.jobId)` to find out which.
+   *
+   * Pass an `idempotencyKey` if this can be retried by anything - a queue, a
+   * user pressing a button twice, or this client's own retry loop, which
+   * refuses to repeat a POST without one. `remember:note-42`, not a fresh
+   * random value per call.
+   */
+  async remember(params, options) {
+    return this.#http.post("/api/v1/remember", params, options);
+  }
+};
+function toQuery(params) {
+  return {
+    ...params.type !== void 0 ? { type: params.type } : {},
+    ...params.state !== void 0 ? { state: params.state } : {},
+    ...params.scope !== void 0 ? { scope: params.scope } : {},
+    ...params.spaceIds !== void 0 ? { spaceIds: params.spaceIds } : {},
+    ...params.createdAfter !== void 0 ? { createdAfter: params.createdAfter } : {},
+    ...params.createdBefore !== void 0 ? { createdBefore: params.createdBefore } : {},
+    ...params.minConfidence !== void 0 ? { minConfidence: params.minConfidence } : {},
+    ...params.includeHistorical !== void 0 ? { includeHistorical: params.includeHistorical } : {}
+  };
+}
+
+// src/resources/search.ts
+var Search = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  /**
+   * Ranked results, with an account of how they were found.
+   *
+   * Read `diagnostics.degraded` before showing the results. Search degrades
+   * rather than fails - with embeddings unavailable it falls back to
+   * deterministic retrieval and still answers - and a UI that cannot tell
+   * degraded from healthy tells the user the system knows nothing when it is
+   * merely looking with one eye.
+   */
+  async query(params, options) {
+    const query = {
+      query: params.query,
+      ...params.limit !== void 0 ? { limit: params.limit } : {},
+      ...params.scope !== void 0 ? { scope: params.scope } : {},
+      ...params.spaceIds !== void 0 ? { spaceIds: params.spaceIds } : {},
+      ...params.types !== void 0 ? { types: params.types } : {},
+      ...params.minScore !== void 0 ? { minScore: params.minScore } : {},
+      ...params.asOf !== void 0 ? { asOf: params.asOf } : {},
+      ...params.includeHistorical !== void 0 ? { includeHistorical: params.includeHistorical } : {},
+      ...params.includeEvidence !== void 0 ? { includeEvidence: params.includeEvidence } : {},
+      ...params.explain !== void 0 ? { explain: params.explain } : {}
+    };
+    return this.#http.get("/api/v1/search", query, options);
+  }
+  /**
+   * A context window, assembled and ready to paste into a prompt.
+   *
+   * A POST that is safe to repeat - it reads and returns, it writes nothing -
+   * so this is one of the few places where retrying without an idempotency key
+   * would be harmless. It still is not retried by default: the request loop
+   * decides by METHOD, and a per-endpoint exception is a rule that holds until
+   * someone adds a POST next to it that does write.
+   */
+  async context(params, options) {
+    return this.#http.post("/api/v1/context", params, options);
+  }
+};
+
+// src/resources/spaces.ts
+var Spaces = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/spaces",
+        pageQuery(params, cursor, {
+          ...params.includeArchived !== void 0 ? { includeArchived: params.includeArchived } : {}
+        }),
+        options
+      )
+    );
+  }
+  async get(id, options) {
+    return this.#http.get(`/api/v1/spaces/${encodeURIComponent(id)}`, void 0, options);
+  }
+  /**
+   * Creates a Space. Answers 201.
+   *
+   * Worth an idempotency key when a person is behind it: a double-clicked
+   * "create Space" button makes two Spaces called Work, and nothing later can
+   * tell which of them memories should have gone into.
+   */
+  async create(params, options) {
+    return this.#http.post("/api/v1/spaces", params, options);
+  }
+  /** Renaming, retention, and archiving - `archived` is a field, not a verb. */
+  async update(id, params, options) {
+    return this.#http.patch(`/api/v1/spaces/${encodeURIComponent(id)}`, params, options);
+  }
+  /**
+   * The memories filed in a Space.
+   *
+   * This endpoint answers `{ data, pagination: { limit } }` with no cursor: it
+   * returns the first `limit` members and stops. Wrapped in a `Paginated`
+   * anyway so it reads like every other list, and it simply yields one page -
+   * a caller who needs more should filter `memories.list` by `spaceIds`, which
+   * is the endpoint that actually pages.
+   */
+  memories(id, params = {}, options) {
+    return new Paginated(
+      () => this.#http.get(
+        `/api/v1/spaces/${encodeURIComponent(id)}/memories`,
+        { ...params.limit !== void 0 ? { limit: params.limit } : {} },
+        options
+      )
+    );
+  }
+  async addMemories(id, memoryIds, options) {
+    return this.#http.post(
+      `/api/v1/spaces/${encodeURIComponent(id)}/memories`,
+      { memoryIds },
+      options
+    );
+  }
+  /**
+   * Removes memberships. The memories themselves are untouched.
+   *
+   * A body on a DELETE, which is unusual and is what the API takes: the
+   * alternative is five hundred ids in a query string, and every proxy in
+   * between has its own limit on how long a URL may be.
+   */
+  async removeMemories(id, memoryIds, options) {
+    return this.#http.delete(
+      `/api/v1/spaces/${encodeURIComponent(id)}/memories`,
+      { memoryIds },
+      options
+    );
+  }
+};
+
+// src/resources/ingestion.ts
+var Sources = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/sources",
+        pageQuery(params, cursor, {
+          ...params.provider !== void 0 ? { provider: params.provider } : {}
+        }),
+        options
+      )
+    );
+  }
+  async get(id, options) {
+    return this.#http.get(`/api/v1/sources/${encodeURIComponent(id)}`, void 0, options);
+  }
+};
+var Documents = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/documents",
+        pageQuery(params, cursor, {
+          ...params.sourceId !== void 0 ? { sourceId: params.sourceId } : {},
+          ...params.status !== void 0 ? { status: params.status } : {}
+        }),
+        options
+      )
+    );
+  }
+  async get(id, options) {
+    return this.#http.get(
+      `/api/v1/documents/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    );
+  }
+};
+var Jobs = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/jobs",
+        pageQuery(params, cursor, {
+          ...params.status !== void 0 ? { status: params.status } : {},
+          ...params.type !== void 0 ? { type: params.type } : {}
+        }),
+        options
+      )
+    );
+  }
+  /**
+   * One job, by id. This is what `remember` hands back a reference to.
+   *
+   * `completed` is the terminal success state - the store's own word, not
+   * `succeeded`. A caller polling for a state the API never writes waits
+   * forever with nothing to show why.
+   */
+  async get(id, options) {
+    return this.#http.get(`/api/v1/jobs/${encodeURIComponent(id)}`, void 0, options);
+  }
+};
+
+// src/resources/knowledge.ts
+var Entities = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/entities",
+        pageQuery(params, cursor, {
+          ...params.type !== void 0 ? { type: params.type } : {},
+          ...params.q !== void 0 ? { q: params.q } : {}
+        }),
+        options
+      )
+    );
+  }
+  async get(id, options) {
+    return this.#http.get(`/api/v1/entities/${encodeURIComponent(id)}`, void 0, options);
+  }
+  /**
+   * Which memories mention this entity, and how.
+   *
+   * Returns MENTIONS - a memory id, a role and a confidence - not the memories
+   * themselves. "Memories about Sam" and "memories Sam appears in" are
+   * different questions, and `role` is what separates them.
+   *
+   * Like the Space membership list, this endpoint answers with a `pagination`
+   * block that carries no cursor, so it yields one page and stops.
+   */
+  memories(id, params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        `/api/v1/entities/${encodeURIComponent(id)}/memories`,
+        pageQuery(params, cursor, {
+          ...params.role !== void 0 ? { role: params.role } : {},
+          ...params.minConfidence !== void 0 ? { minConfidence: params.minConfidence } : {}
+        }),
+        options
+      )
+    );
+  }
+};
+var Graph = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  async traverse(params, options) {
+    return this.#http.get(
+      "/api/v1/graph",
+      {
+        from: params.from,
+        ...params.depth !== void 0 ? { depth: params.depth } : {},
+        ...params.maxNodes !== void 0 ? { maxNodes: params.maxNodes } : {},
+        ...params.memoryLimit !== void 0 ? { memoryLimit: params.memoryLimit } : {}
+      },
+      options
+    );
+  }
+};
+var Conflicts = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/conflicts",
+        pageQuery(params, cursor, {
+          ...params.includeResolved !== void 0 ? { includeResolved: params.includeResolved } : {},
+          ...params.type !== void 0 ? { type: params.type } : {}
+        }),
+        options
+      )
+    );
+  }
+  async get(id, options) {
+    return this.#http.get(
+      `/api/v1/conflicts/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    );
+  }
+  /**
+   * Settles one.
+   *
+   * `keep` names the winner and supersedes the loser; it does not delete it.
+   * `dismiss` records that the detector was wrong, which is worth knowing when
+   * the same pair trips it again.
+   *
+   * The parameter type is a union, so `keep` without a `keepId` does not
+   * compile. The server rejects it too - this just moves the failure from a
+   * 400 in production to a red squiggle.
+   */
+  async resolve(id, params, options) {
+    return this.#http.post(
+      `/api/v1/conflicts/${encodeURIComponent(id)}/resolve`,
+      params,
+      options
+    );
+  }
+};
+
+// src/resources/conversations.ts
+var Conversations = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/conversations",
+        pageQuery(params, cursor, {
+          ...params.channel !== void 0 ? { channel: params.channel } : {}
+        }),
+        options
+      )
+    );
+  }
+  async get(id, options) {
+    return this.#http.get(
+      `/api/v1/conversations/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    );
+  }
+  async create(params = {}, options) {
+    return this.#http.post("/api/v1/conversations", params, options);
+  }
+  messages(id, params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        `/api/v1/conversations/${encodeURIComponent(id)}/messages`,
+        pageQuery(params, cursor, {}),
+        options
+      )
+    );
+  }
+  /**
+   * Appends turns, and by default extracts memories from them.
+   *
+   * Check `extracting` on the result. With no queue configured the turns are
+   * stored and never become memory, and the API says so in `note` rather than
+   * reporting a success - a caller that ignores it believes a memory is on its
+   * way that never arrives.
+   *
+   * `system` and `tool` turns are stored but never extracted: a system prompt
+   * is configuration, and remembering it would file our own instructions as
+   * the user's facts.
+   *
+   * Give this an `idempotencyKey`. Appending the same turn twice is the most
+   * likely duplicate in the whole API - a client reconnecting after a dropped
+   * response has no other way to tell whether its last write landed.
+   */
+  async append(id, params, options) {
+    return this.#http.post(
+      `/api/v1/conversations/${encodeURIComponent(id)}/messages`,
+      params,
+      options
+    );
+  }
+};
+
+// src/resources/integrations.ts
+var Integrations = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  list(params = {}, options) {
+    return new Paginated(
+      (cursor) => this.#http.get(
+        "/api/v1/integrations",
+        pageQuery(params, cursor, {
+          ...params.provider !== void 0 ? { provider: params.provider } : {},
+          ...params.status !== void 0 ? { status: params.status } : {}
+        }),
+        options
+      )
+    );
+  }
+  /** Providers that can be connected at all. Not the user's own connections. */
+  async available(options) {
+    return this.#http.get("/api/v1/integrations/available", void 0, options);
+  }
+  async get(id, options) {
+    return this.#http.get(
+      `/api/v1/integrations/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    );
+  }
+  async connect(params, options) {
+    return this.#http.post(
+      "/api/v1/integrations/connect",
+      params,
+      options
+    );
+  }
+  async update(id, params, options) {
+    return this.#http.patch(
+      `/api/v1/integrations/${encodeURIComponent(id)}`,
+      params,
+      options
+    );
+  }
+  /**
+   * Asks for a sync now rather than waiting for the schedule. Answers 202.
+   *
+   * `full` re-reads everything and is deliberately opt-in: on a large Drive
+   * that is thousands of documents and a real bill. The incremental default is
+   * what should run almost always.
+   */
+  async sync(id, params = {}, options) {
+    return this.#http.post(
+      `/api/v1/integrations/${encodeURIComponent(id)}/sync`,
+      params,
+      options
+    );
+  }
+  /**
+   * Destroys the credentials. The row stays.
+   *
+   * History still has to attribute the memories this connection produced, and
+   * deleting the row would leave them pointing at nothing.
+   */
+  async disconnect(id, options) {
+    return this.#http.delete(
+      `/api/v1/integrations/${encodeURIComponent(id)}`,
+      void 0,
+      options
+    );
+  }
+};
+
+// src/resources/health.ts
+var Health = class {
+  #http;
+  constructor(http) {
+    this.#http = http;
+  }
+  async live(options) {
+    return this.#http.get("/health/live", void 0, options);
+  }
+  async ready(options) {
+    return this.#http.get("/health/ready", void 0, options);
+  }
+};
+
+// src/client.ts
+var PersistMemory = class {
+  memories;
+  search;
+  spaces;
+  sources;
+  documents;
+  jobs;
+  entities;
+  graph;
+  conflicts;
+  conversations;
+  integrations;
+  health;
+  #http;
+  constructor(options) {
+    this.#http = new HttpClient(options);
+    this.memories = new Memories(this.#http);
+    this.search = new Search(this.#http);
+    this.spaces = new Spaces(this.#http);
+    this.sources = new Sources(this.#http);
+    this.documents = new Documents(this.#http);
+    this.jobs = new Jobs(this.#http);
+    this.entities = new Entities(this.#http);
+    this.graph = new Graph(this.#http);
+    this.conflicts = new Conflicts(this.#http);
+    this.conversations = new Conversations(this.#http);
+    this.integrations = new Integrations(this.#http);
+    this.health = new Health(this.#http);
+  }
+  /**
+   * An escape hatch for an endpoint this package has not caught up with.
+   *
+   * Typed as `unknown` on purpose: a caller reaching past the typed surface is
+   * taking responsibility for the shape, and handing them `any` would let that
+   * responsibility spread silently through their codebase.
+   */
+  async request(method, path, body, options) {
+    if (method === "GET") return this.#http.get(path, void 0, options);
+    if (method === "POST") return this.#http.post(path, body, options);
+    if (method === "PATCH") return this.#http.patch(path, body, options);
+    return this.#http.delete(path, body, options);
+  }
+  /** Never the key. See `HttpClient.toJSON`, which this delegates to. */
+  toJSON() {
+    return this.#http.toJSON();
+  }
+  [Symbol.for("nodejs.util.inspect.custom")]() {
+    return this.#http.toJSON();
+  }
+};
+export {
+  AbortError,
+  AuthenticationError,
+  ConflictError,
+  ConnectionError,
+  DEFAULT_BACKOFF,
+  NotFoundError,
+  Paginated,
+  PermissionDeniedError,
+  PersistMemory,
+  PersistMemoryError,
+  RateLimitError,
+  ServerError,
+  TimeoutError,
+  ValidationError,
+  backoffMs,
+  delayFor
+};
+//# sourceMappingURL=index.js.map