@alexein/sdk 0.0.0-stage → 0.3.0

package/dist/chunk-7KPDU3YV.cjs

@@ -0,0 +1,920 @@
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } async function _asyncNullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return await rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }// src/json.ts
+var object = (value) => typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+var list = (value) => Array.isArray(value) ? value : [];
+var objects = (value) => list(value).map(object);
+var text = (value) => typeof value === "string" ? value : value === void 0 || value === null ? "" : String(value);
+var maybe = (value) => typeof value === "string" ? value : value === void 0 || value === null ? null : String(value);
+var strings = (value) => list(value).map(text);
+var maybeStrings = (value) => Array.isArray(value) ? strings(value) : null;
+var count = (value) => typeof value === "number" ? value : Number(value) || 0;
+var maybeCount = (value) => value === void 0 || value === null ? null : count(value);
+var bool = (value) => value === true;
+function compact(body) {
+  return Object.fromEntries(
+    Object.entries(body).filter(([, value]) => value !== void 0 && value !== null)
+  );
+}
+
+// src/memories.ts
+function parseFact(value) {
+  const raw = object(value);
+  return {
+    type: "fact",
+    ref: text(raw.ref),
+    text: text(raw.text),
+    source: maybe(raw.source),
+    date: maybe(raw.date),
+    raw
+  };
+}
+function parseExcerpt(value) {
+  const raw = object(value);
+  return {
+    type: "excerpt",
+    ref: text(raw.ref),
+    text: text(raw.text),
+    date: maybe(raw.date),
+    addedAt: maybe(raw.added_at),
+    session: maybe(raw.session),
+    roles: strings(raw.roles),
+    raw
+  };
+}
+function parseMemory(value) {
+  const raw = object(value);
+  if (raw.type === "known") return { type: "known", text: text(raw.text), raw };
+  if (raw.type === "fact") return parseFact(raw);
+  if (raw.type === "excerpt") return parseExcerpt(raw);
+  return void 0;
+}
+function parseMemories(value) {
+  const out = [];
+  for (const entry of Array.isArray(value) ? value : []) {
+    const memory = parseMemory(entry);
+    if (memory) out.push(memory);
+  }
+  return out;
+}
+function refsOf(memories) {
+  return memories.flatMap((m) => m.type === "known" || !m.ref ? [] : [m.ref]);
+}
+
+// src/search.ts
+function line(memory) {
+  const dated = memory.type === "excerpt" && memory.date ? `${memory.date.slice(0, 10)}: ` : "";
+  return `- ${dated}${memory.text}`;
+}
+var SearchResult = class _SearchResult {
+  constructor(query, answerable, notes, memories, sources2, failed, raw) {
+    this.query = query;
+    this.answerable = answerable;
+    this.notes = notes;
+    this.memories = memories;
+    this.sources = sources2;
+    this.failed = failed;
+    this.raw = raw;
+  }
+  
+  
+  
+  
+  
+  
+  
+  static parse(value) {
+    const raw = object(value);
+    return new _SearchResult(
+      text(raw.query),
+      typeof raw.answerable === "boolean" ? raw.answerable : null,
+      strings(raw.notes),
+      parseMemories(raw.memories),
+      Array.isArray(raw.sources) ? list(raw.sources).map(object) : null,
+      false,
+      raw
+    );
+  }
+  /** What a `failOpen` client answers when memory could not be reached. */
+  static unavailable(query) {
+    return new _SearchResult(query, null, [], [], null, true, {});
+  }
+  get known() {
+    return this.memories.filter((m) => m.type === "known");
+  }
+  get facts() {
+    return this.memories.filter((m) => m.type === "fact");
+  }
+  get excerpts() {
+    return this.memories.filter((m) => m.type === "excerpt");
+  }
+  /** Every ref, in order: each opens with `user.open(ref)`. */
+  get refs() {
+    return refsOf(this.memories);
+  }
+  /**
+   * The text to paste into a prompt: each note on its own line, a blank line, then each memory on
+   * its own line as `- <text>` (an excerpt with a date as `- <YYYY-MM-DD>: <text>`), cut at a whole
+   * memory so it is never longer than `maxChars`. Empty when there are no memories, or when not
+   * even the first fits. The Python client and the n8n node write the same text.
+   */
+  context(maxChars = 4e3) {
+    const head = this.notes.length ? `${this.notes.join("\n")}
+
+` : "";
+    let out = "";
+    for (const memory of this.memories) {
+      const grown = `${out || head}${out ? "\n" : ""}${line(memory)}`;
+      if (grown.length > maxChars) break;
+      out = grown;
+    }
+    return out;
+  }
+};
+
+// src/errors.ts
+var AlexeinError = class extends Error {
+  /** The HTTP status, or null when no response came back. */
+  
+  /** The API's own explanation; for a transport failure, what went wrong. */
+  
+  /** On a 422: each field the body got wrong. Empty otherwise. */
+  
+  /**
+   * The request's id: the `X-Request-Id` this client sent, which the API logs and answers with.
+   * Quote it when you ask for help, or find the request in the console's request logs.
+   */
+  
+  constructor(message, fields = {}) {
+    super(message, fields.cause === void 0 ? void 0 : { cause: fields.cause });
+    this.name = new.target.name;
+    this.status = _nullishCoalesce(fields.status, () => ( null));
+    this.detail = _nullishCoalesce(fields.detail, () => ( message));
+    this.errors = _nullishCoalesce(fields.errors, () => ( []));
+    this.requestId = _nullishCoalesce(fields.requestId, () => ( null));
+  }
+  /**
+   * Whether this means memory is unavailable - unreachable, too slow, too busy or failing - rather
+   * than that the request or the key is wrong. A `failOpen` client rides out an outage; a mistake
+   * still throws.
+   */
+  get outage() {
+    return this.status !== null && (this.status === 429 || this.status >= 500);
+  }
+};
+var AuthenticationError = class extends AlexeinError {
+};
+var PermissionDeniedError = class extends AlexeinError {
+};
+var NotFoundError = class extends AlexeinError {
+};
+var InvalidRequestError = class extends AlexeinError {
+};
+var RateLimitError = class extends AlexeinError {
+};
+var ServiceUnavailableError = class extends AlexeinError {
+};
+var APIConnectionError = class extends AlexeinError {
+  get outage() {
+    return true;
+  }
+};
+var APITimeoutError = class extends APIConnectionError {
+};
+function kindOf(status2) {
+  if (status2 === 401) return AuthenticationError;
+  if (status2 === 403) return PermissionDeniedError;
+  if (status2 === 404) return NotFoundError;
+  if (status2 === 429) return RateLimitError;
+  if (status2 >= 500) return ServiceUnavailableError;
+  if (status2 >= 400) return InvalidRequestError;
+  return AlexeinError;
+}
+function fieldErrors(value) {
+  return list(value).map((entry) => {
+    const error = object(entry);
+    if (Array.isArray(error.loc)) {
+      const at = error.loc[0] === "body" ? error.loc.slice(1) : error.loc;
+      return { field: at.map(String).join("."), message: text(error.msg) };
+    }
+    return { field: text(error.field), message: text(error.message) };
+  });
+}
+function errorFor(status2, body, requestId2) {
+  const errors = fieldErrors(_nullishCoalesce(body.errors, () => ( (Array.isArray(body.detail) ? body.detail : []))));
+  const detail = typeof body.detail === "string" ? body.detail : errors.map((e) => e.field ? `${e.field}: ${e.message}` : e.message).join("; ");
+  const Kind = kindOf(status2);
+  return new Kind(detail ? `${status2}: ${detail}` : String(status2), {
+    status: status2,
+    detail,
+    errors,
+    requestId: requestId2
+  });
+}
+function unreached(error, requestId2 = null) {
+  const name = error instanceof Error ? error.name : "";
+  const said = error instanceof Error ? error.message : String(error);
+  if (name === "TimeoutError" || name === "AbortError") {
+    return new APITimeoutError(`Alexein did not answer in time: ${said}`, {
+      cause: error,
+      requestId: requestId2
+    });
+  }
+  return new APIConnectionError(`Alexein could not be reached: ${said}`, {
+    cause: error,
+    requestId: requestId2
+  });
+}
+
+// src/version.ts
+var VERSION = "0.3.0";
+
+// src/settings.ts
+var DEFAULT_BASE_URL = "https://api.alexein.ai";
+var DEFAULT_TIMEOUT_MS = 6e4;
+var DEFAULT_RETRIES = 2;
+var KEYS_PAGE = "https://app.alexein.ai/console/keys";
+var INTEGRATION = /^[a-z0-9][a-z0-9._-]{0,31}$/;
+var USER_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,34}$/;
+function environment(name) {
+  const env = _optionalChain([globalThis, 'access', _ => _.process, 'optionalAccess', _2 => _2.env]);
+  return _optionalChain([env, 'optionalAccess', _3 => _3[name]]) || void 0;
+}
+function normalizeBaseUrl(url) {
+  return url.trim().replace(/\/+$/, "").replace(/\/v2$/, "").replace(/\/+$/, "");
+}
+function checkedUserId(id) {
+  if (typeof id !== "string" || !USER_ID.test(id)) {
+    throw new RangeError(
+      `not a usable app user id: ${JSON.stringify(id)} (1 to 35 letters, digits, '.', '_' and '-', beginning with a letter or digit)`
+    );
+  }
+  return id;
+}
+function count2(name, value, least) {
+  if (!Number.isFinite(value) || value < least) {
+    throw new RangeError(`${name} must be a number of at least ${least}: ${value}`);
+  }
+  return value;
+}
+function settings(options) {
+  const key = _nullishCoalesce(_nullishCoalesce(options.apiKey, () => ( environment("ALEXEIN_API_KEY"))), () => ( ""));
+  if (!key) {
+    throw new AlexeinError(
+      `No API key: pass apiKey, or set ALEXEIN_API_KEY. Make one in the console, under API keys: ${KEYS_PAGE}`
+    );
+  }
+  const integration = _nullishCoalesce(options.integration, () => ( null));
+  if (integration !== null && !INTEGRATION.test(integration)) {
+    throw new RangeError(
+      `integration must be one short lowercase word: ${JSON.stringify(integration)}`
+    );
+  }
+  const given = globalThis.fetch;
+  const send = _nullishCoalesce(options.fetch, () => ( (given ? given.bind(globalThis) : void 0)));
+  if (!send) throw new AlexeinError("No fetch in this runtime: pass one as the fetch option.");
+  return {
+    key,
+    baseUrl: normalizeBaseUrl(
+      _nullishCoalesce(_nullishCoalesce(options.baseUrl, () => ( environment("ALEXEIN_API_URL"))), () => ( DEFAULT_BASE_URL))
+    ),
+    timeout: count2("timeout", _nullishCoalesce(options.timeout, () => ( DEFAULT_TIMEOUT_MS)), 1),
+    maxRetries: Math.floor(count2("maxRetries", _nullishCoalesce(options.maxRetries, () => ( DEFAULT_RETRIES)), 0)),
+    failOpen: _nullishCoalesce(options.failOpen, () => ( false)),
+    integration,
+    userAgent: `alexein-js/${VERSION}${integration ? ` ${integration}` : ""}`,
+    log: _nullishCoalesce(options.logger, () => ( ((message) => console.warn(message)))),
+    fetch: send
+  };
+}
+
+// src/reads.ts
+function parseMemoriesResult(value) {
+  const raw = object(value);
+  const memories = parseMemories(raw.memories);
+  return {
+    memories,
+    pattern: maybe(raw.pattern),
+    total: maybeCount(raw.total),
+    places: maybeStrings(raw.places),
+    raw,
+    [Symbol.iterator]: () => memories[Symbol.iterator]()
+  };
+}
+function parseOpened(value) {
+  const raw = object(value);
+  const memory = object(raw.memory);
+  return {
+    memory: memory.type === "fact" ? parseFact(memory) : parseExcerpt(memory),
+    sources: objects(raw.sources).map(parseExcerpt),
+    raw
+  };
+}
+function parseHistory(value) {
+  const raw = object(value);
+  return {
+    subject: text(raw.subject),
+    values: objects(raw.values).map((v) => ({
+      attribute: text(v.attribute),
+      value: text(v.value),
+      since: maybe(v.since),
+      negated: v.negated === true,
+      raw: v
+    })),
+    suggestions: maybeStrings(raw.suggestions),
+    raw
+  };
+}
+function parseSource(raw) {
+  return {
+    provider: text(raw.provider),
+    source: text(raw.source),
+    connection: text(raw.connection),
+    items: count(raw.items),
+    ended: count(raw.ended),
+    newest: maybe(raw.newest),
+    raw
+  };
+}
+function parseSources(value) {
+  const raw = object(value);
+  return { sources: objects(raw.sources).map(parseSource), raw };
+}
+function parseSummary(value) {
+  const raw = object(value);
+  return {
+    items: count(raw.items),
+    first: maybe(raw.first),
+    last: maybe(raw.last),
+    sources: objects(raw.sources).map(parseSource),
+    known: strings(raw.known),
+    raw
+  };
+}
+function parseOpenItems(value) {
+  const raw = object(value);
+  return {
+    items: objects(raw.items).map((i) => ({
+      ref: text(i.ref),
+      text: text(i.text),
+      date: maybe(i.date),
+      addedAt: maybe(i.added_at),
+      ageDays: maybeCount(i.age_days),
+      raw: i
+    })),
+    followUps: objects(raw.follow_ups).map((f) => ({
+      title: maybe(f.title),
+      who: maybe(f.who),
+      date: maybe(f.date),
+      ageDays: maybeCount(f.age_days),
+      raw: f
+    })),
+    raw
+  };
+}
+
+// src/pages.ts
+function parseFactsPage(value) {
+  const raw = object(value);
+  return { facts: objects(raw.facts).map(parseFact), next: maybe(raw.next), raw };
+}
+function parseStoredItem(value) {
+  const raw = object(value);
+  const author = raw.author;
+  return {
+    id: text(raw.id),
+    kind: maybe(raw.kind),
+    text: text(raw.text),
+    title: maybe(raw.title),
+    at: maybe(raw.at),
+    author: typeof author === "string" ? author : author ? object(author) : null,
+    role: maybe(raw.role),
+    session: maybe(raw.session),
+    about: maybeStrings(raw.about),
+    metadata: raw.metadata ? object(raw.metadata) : null,
+    expires: maybe(raw.expires),
+    status: text(raw.status),
+    raw
+  };
+}
+function parseFound(value) {
+  const raw = object(value);
+  return raw.found === false || !raw.item ? null : parseStoredItem(raw.item);
+}
+function parseItemsPage(value) {
+  const raw = object(value);
+  return { items: objects(raw.items).map(parseStoredItem), next: maybe(raw.next), raw };
+}
+function parseUsersPage(value) {
+  const raw = object(value);
+  const users2 = objects(raw.users).map((u) => ({
+    user: text(u.user),
+    items: count(u.items),
+    facts: count(u.facts),
+    lastWrite: maybe(u.last_write),
+    raw: u
+  }));
+  return { users: users2, next: maybe(raw.next), raw };
+}
+function parseExportPage(value) {
+  const raw = object(value);
+  return {
+    user: text(raw.user),
+    exportedAt: maybe(raw.exported_at),
+    records: objects(raw.records).map((r) => ({ ...r, type: text(r.type) })),
+    next: maybe(raw.next),
+    withheld: strings(raw.withheld),
+    raw
+  };
+}
+function parseMe(value) {
+  const raw = object(value);
+  return {
+    kind: text(raw.kind),
+    org: maybe(raw.org),
+    project: maybe(raw.project),
+    keyId: maybe(raw.key_id),
+    writes: bool(raw.writes),
+    label: maybe(raw.label),
+    createdBy: maybe(raw.created_by),
+    orgName: maybe(raw.org_name),
+    projectName: maybe(raw.project_name),
+    space: maybe(raw.space),
+    raw
+  };
+}
+async function* paged(page, entries) {
+  let cursor;
+  do {
+    const got = await page(cursor);
+    yield* entries(got);
+    cursor = _nullishCoalesce(got.next, () => ( void 0));
+  } while (cursor);
+}
+
+// src/writes.ts
+function addResult(items2, waiting, failed, raw) {
+  return { items: items2, waiting, failed, ids: items2.map((i) => i.id), raw };
+}
+function parseAddResult(value) {
+  const raw = object(value);
+  const items2 = objects(raw.items).map((i) => ({
+    id: text(i.id),
+    status: text(i.status),
+    redacted: i.redacted ? object(i.redacted) : null,
+    raw: i
+  }));
+  return addResult(items2, count(raw.waiting), false, raw);
+}
+function mergedAdd(results, failed = false) {
+  if (results.length === 1 && !failed) return results[0];
+  const items2 = results.flatMap((r) => r.items);
+  const waiting = results.reduce((n, r) => n + r.waiting, 0);
+  const raw = results.length ? { items: items2.map((i) => i.raw), waiting } : {};
+  return addResult(items2, waiting, failed, raw);
+}
+function parseStatuses(value) {
+  const raw = object(value);
+  const items2 = objects(raw.items).map((i) => ({
+    id: text(i.id),
+    status: text(i.status),
+    reason: maybe(i.reason),
+    raw: i
+  }));
+  return { items: items2, byId: Object.fromEntries(items2.map((i) => [i.id, i.status])), raw };
+}
+function parseForgotten(value) {
+  const raw = object(value);
+  const e = object(raw.erased);
+  return {
+    erased: {
+      items: count(e.items),
+      facts: count(e.facts),
+      versions: count(e.versions),
+      waiting: count(e.waiting),
+      relearning: count(e.relearning)
+    },
+    complete: bool(raw.complete),
+    raw
+  };
+}
+function parseCorrection(value) {
+  const raw = object(value);
+  return {
+    retracted: text(raw.retracted),
+    text: maybe(raw.text),
+    replacement: maybe(raw.replacement),
+    raw
+  };
+}
+function parseVersions(value) {
+  const raw = object(value);
+  return {
+    id: text(raw.id),
+    state: text(raw.state),
+    history: objects(raw.history).map((h) => ({
+      event: text(h.event),
+      at: maybe(h.at),
+      version: maybeCount(h.version),
+      item: h.item ? object(h.item) : null,
+      why: maybe(h.why),
+      raw: h
+    })),
+    raw
+  };
+}
+function parseDeleted(value) {
+  const raw = object(value);
+  return { user: text(raw.user), deleted: bool(raw.deleted), raw };
+}
+
+// src/calls.ts
+var kinds = (kind) => kind === void 0 ? void 0 : Array.isArray(kind) ? kind : [kind];
+function post(route, parse, body = {}) {
+  return { method: "POST", path: `/memory/${route}`, body: compact(body), parse };
+}
+var me = () => ({ method: "GET", path: "/me", parse: parseMe });
+var users = (o) => post("users", parseUsersPage, { limit: o.limit, cursor: o.cursor });
+var deleteUser = () => post("users/delete", parseDeleted);
+var add = (body, key) => ({
+  method: "POST",
+  path: "/memory/add",
+  body,
+  headers: { "Idempotency-Key": key },
+  parse: parseAddResult
+});
+var search = (query, o) => post("search", SearchResult.parse, {
+  query,
+  before: o.before,
+  after: o.after,
+  filters: o.filters,
+  provider: o.provider,
+  source: o.source,
+  kind: kinds(o.kind),
+  fast: o.fast
+});
+var grep = (pattern, o) => post("grep", parseMemoriesResult, {
+  pattern,
+  limit: o.limit,
+  provider: o.provider,
+  source: o.source,
+  kind: kinds(o.kind)
+});
+var latest = (o) => post("latest", parseMemoriesResult, {
+  k: o.k,
+  place: o.place,
+  after: o.after,
+  before: o.before,
+  filters: o.filters,
+  provider: o.provider,
+  source: o.source,
+  kind: kinds(o.kind)
+});
+var around = (ref, width) => post("around", parseMemoriesResult, { ref, width });
+var open = (ref) => post("open", parseOpened, { ref });
+var history = (subject, attribute) => post("history", parseHistory, { subject, attribute });
+var summary = () => post("summary", parseSummary);
+var facts = (o) => post("facts", parseFactsPage, { limit: o.limit, cursor: o.cursor });
+var openItems = (o) => post("open_items", parseOpenItems, {
+  kind: kinds(o.kind),
+  provider: o.provider,
+  place: o.place,
+  mine: o.mine,
+  within_days: o.withinDays,
+  limit: o.limit
+});
+var sources = () => post("sources", parseSources);
+var items = (o) => post("items", parseItemsPage, { limit: o.limit, cursor: o.cursor, filters: o.filters });
+var item = (id) => post("item", parseFound, { id });
+var status = (ids) => post("status", parseStatuses, { items: ids });
+function forget(named) {
+  const body = compact({
+    items: _optionalChain([named, 'access', _4 => _4.items, 'optionalAccess', _5 => _5.length]) ? named.items : void 0,
+    sessions: _optionalChain([named, 'access', _6 => _6.sessions, 'optionalAccess', _7 => _7.length]) ? named.sessions : void 0,
+    refs: _optionalChain([named, 'access', _8 => _8.refs, 'optionalAccess', _9 => _9.length]) ? named.refs : void 0
+  });
+  if (!Object.keys(body).length) {
+    throw new RangeError("forget needs at least one of items, sessions or refs");
+  }
+  return post("forget", parseForgotten, body);
+}
+var correct = (ref, replacement) => post("correct", parseCorrection, { ref, replacement });
+var versions = (id) => post("versions", parseVersions, { id });
+var exportPage = (o) => post("export", parseExportPage, { limit: o.limit, cursor: o.cursor });
+
+// src/items.ts
+var BATCH = 500;
+function shape(given, defaults) {
+  const item2 = typeof given === "string" ? { text: given } : { ...given };
+  if (typeof item2.text !== "string" || !item2.text) {
+    throw new TypeError(`an item needs text: ${JSON.stringify(given)}`);
+  }
+  const own = Object.fromEntries(Object.entries(item2).filter(([, v]) => v !== void 0));
+  return { ...defaults, ...own };
+}
+function batches(items2, options) {
+  const { wait, redact, ...fields } = options;
+  const defaults = compact(fields);
+  const given = typeof items2 === "string" || !Array.isArray(items2) ? [items2] : items2;
+  const shaped = given.map((item2) => shape(item2, defaults));
+  if (!shaped.length) return [];
+  const call = crypto.randomUUID();
+  const out = [];
+  for (let at = 0; at < shaped.length; at += BATCH) {
+    out.push({
+      body: compact({ items: shaped.slice(at, at + BATCH), wait, redact }),
+      key: `${call}-${at / BATCH}`
+    });
+  }
+  return out;
+}
+
+// src/user.ts
+var User = class {
+  /** @internal Made by `memory.user(id)`. */
+  constructor(transport, id, failOpen, log) {
+    this.transport = transport;
+    this.id = id;
+    this.failOpen = failOpen;
+    this.log = log;
+  }
+  
+  
+  
+  
+  send(call) {
+    return this.transport.send(call, this.id);
+  }
+  /**
+   * Remember text: a string, an item, or a list of either. The options fill in each item's unset
+   * fields. More than 500 items go as several requests; a retry never saves an item twice.
+   */
+  async add(items2, options = {}) {
+    const results = [];
+    for (const batch of batches(items2, options)) {
+      try {
+        results.push(await this.send(add(batch.body, batch.key)));
+      } catch (error) {
+        this.rideOut(error, "add");
+        return mergedAdd(results, true);
+      }
+    }
+    return mergedAdd(results);
+  }
+  /** What memory holds for a question: known lines, facts and excerpts, in order. */
+  async search(query, options = {}) {
+    try {
+      return await this.send(search(query, options));
+    } catch (error) {
+      this.rideOut(error, "search");
+      return SearchResult.unavailable(query);
+    }
+  }
+  /** Excerpts holding an exact phrase, ignoring case. */
+  grep(pattern, options = {}) {
+    return this.send(grep(pattern, options));
+  }
+  /** The most recent excerpts, newest first; with `after` and `before`, everything between. */
+  latest(options = {}) {
+    return this.send(latest(options));
+  }
+  /** The excerpts just before and after one, from the same conversation, in order. */
+  around(ref, options = {}) {
+    return this.send(around(ref, options.width));
+  }
+  /** One memory by its ref, whole: an excerpt, or a fact with the excerpts it came from. */
+  open(ref) {
+    return this.send(open(ref));
+  }
+  /** Every value a subject was stated to have, by attribute, oldest first. */
+  history(subject, options = {}) {
+    return this.send(history(subject, options.attribute));
+  }
+  /** This memory in brief: its items, their span, the connected sources and the known lines. */
+  summary() {
+    return this.send(summary());
+  }
+  /** The facts memory learned, newest first, a page at a time. */
+  facts(options = {}) {
+    return this.send(facts(options));
+  }
+  /** Every fact, across pages. */
+  iterFacts(options = {}) {
+    return paged(
+      (cursor) => this.facts({ ...options, cursor }),
+      (page) => page.facts
+    );
+  }
+  /** The issues and pull requests still open, and the asks nobody answered. */
+  openItems(options = {}) {
+    return this.send(openItems(options));
+  }
+  /** What each connected app delivered to this memory. */
+  sources() {
+    return this.send(sources());
+  }
+  /** The items added, newest first, as they were given, a page at a time. */
+  items(options = {}) {
+    return this.send(items(options));
+  }
+  /** Every item, across pages. */
+  iterItems(options = {}) {
+    return paged(
+      (cursor) => this.items({ ...options, cursor }),
+      (page) => page.items
+    );
+  }
+  /** One added item by its id, whole; null when memory holds none by that id. */
+  item(itemId) {
+    return this.send(item(itemId));
+  }
+  /** How far each item has got: `queued`, `stored`, `processed` or `unknown`. */
+  status(ids) {
+    return this.send(status(ids));
+  }
+  /** Erase these items, sessions and memories (by ref), with every copy and all learned from them. */
+  async forget(named) {
+    return this.send(forget(named));
+  }
+  /** Retract one fact for good, by its ref; a `replacement` is kept as a note. */
+  correct(ref, replacement) {
+    return this.send(correct(ref, replacement));
+  }
+  /** Every version of one added item, oldest first. Takes a key that writes. */
+  versions(itemId) {
+    return this.send(versions(itemId));
+  }
+  /** Everything memory holds for this app user, a page at a time. */
+  export(options = {}) {
+    return this.send(exportPage(options));
+  }
+  /** Every export record, across pages. */
+  iterExport(options = {}) {
+    return paged(
+      (cursor) => this.export({ ...options, cursor }),
+      (page) => page.records
+    );
+  }
+  /** Erase this app user whole: every item, fact and version. Not undone. */
+  delete() {
+    return this.send(deleteUser());
+  }
+  /**
+   * Throw `error` unless this client fails open and it is an outage; then log it, and the caller
+   * answers empty. Memory being down costs a reply its memory, not the reply.
+   */
+  rideOut(error, what) {
+    if (!(this.failOpen && error instanceof AlexeinError && error.outage)) throw error;
+    this.log(`Alexein is unavailable, so ${what} for ${this.id} was skipped: ${error.message}`);
+  }
+};
+
+// src/transport.ts
+var RETRIED = /* @__PURE__ */ new Set([429, 503]);
+var LONGEST_WAIT_MS = 6e4;
+var SETS_USER_AGENT = typeof globalThis.document === "undefined";
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function requestId() {
+  return `req_${globalThis.crypto.randomUUID().replaceAll("-", "")}`;
+}
+function pauseFor(attempt, response) {
+  if (response !== void 0) {
+    if (!RETRIED.has(response.status)) return void 0;
+    const after = (_nullishCoalesce(response.headers.get("Retry-After"), () => ( ""))).trim();
+    if (/^\d+(\.\d+)?$/.test(after)) {
+      const ms = Number(after) * 1e3;
+      return ms <= LONGEST_WAIT_MS ? ms : void 0;
+    }
+  }
+  return 500 * 2 ** attempt * (0.75 + Math.random() * 0.5);
+}
+async function bodyOf(response) {
+  const said = await response.text();
+  if (!said) return { body: {}, said };
+  try {
+    return { body: JSON.parse(said), said };
+  } catch (e2) {
+    return { body: void 0, said };
+  }
+}
+var Transport = class {
+  constructor(settings2) {
+    this.settings = settings2;
+  }
+  
+  /** Send `call` for app user `user` (none for `me` and `users`), retrying as the API asks. */
+  async send(call, user) {
+    const rid = requestId();
+    for (let attempt = 0; ; attempt++) {
+      let response;
+      let failure;
+      try {
+        response = await this.attempt(call, user, rid);
+      } catch (error) {
+        failure = unreached(error, rid);
+      }
+      if (_optionalChain([response, 'optionalAccess', _10 => _10.ok])) return this.answer(response, call, rid);
+      const pause = attempt < this.settings.maxRetries ? pauseFor(attempt, response) : void 0;
+      if (pause === void 0) throw await _asyncNullishCoalesce(failure, async () => ( await this.refusal(response, rid)));
+      await _optionalChain([response, 'optionalAccess', _11 => _11.body, 'optionalAccess', _12 => _12.cancel, 'call', _13 => _13(), 'access', _14 => _14.catch, 'call', _15 => _15(() => {
+      })]);
+      await sleep(pause);
+    }
+  }
+  attempt(call, user, rid) {
+    const headers = {
+      Authorization: `Bearer ${this.settings.key}`,
+      "X-Request-Id": rid,
+      ...call.headers
+    };
+    if (SETS_USER_AGENT) headers["User-Agent"] = this.settings.userAgent;
+    if (user !== void 0) headers["X-Alexein-User"] = user;
+    if (call.method === "POST") headers["Content-Type"] = "application/json";
+    return this.settings.fetch(`${this.settings.baseUrl}/v2${call.path}`, {
+      method: call.method,
+      headers,
+      body: call.method === "POST" ? JSON.stringify(_nullishCoalesce(call.body, () => ( {}))) : void 0,
+      signal: AbortSignal.timeout(this.settings.timeout)
+    });
+  }
+  async answer(response, call, rid) {
+    const { body, said } = await bodyOf(response);
+    if (body === void 0) {
+      throw new AlexeinError(`${response.status}: the answer is not JSON: ${said.slice(0, 200)}`, {
+        status: response.status,
+        requestId: _nullishCoalesce(response.headers.get("X-Request-Id"), () => ( rid))
+      });
+    }
+    return call.parse(body);
+  }
+  async refusal(response, rid) {
+    const { body, said } = await bodyOf(response);
+    const json = body === void 0 ? { detail: said.trim() } : object(body);
+    return errorFor(response.status, json, _nullishCoalesce(response.headers.get("X-Request-Id"), () => ( rid)));
+  }
+};
+
+// src/client.ts
+var Memory = class {
+  /** The API's host, without `/v2`. */
+  
+  /** Milliseconds one attempt may take. */
+  
+  
+  
+  /** The word in the User-Agent, or null. */
+  
+  #settings;
+  #transport;
+  constructor(options = {}) {
+    this.#settings = settings(options);
+    this.#transport = new Transport(this.#settings);
+    this.baseUrl = this.#settings.baseUrl;
+    this.timeout = this.#settings.timeout;
+    this.maxRetries = this.#settings.maxRetries;
+    this.failOpen = this.#settings.failOpen;
+    this.integration = this.#settings.integration;
+  }
+  /** What this key is: its organisation, project, and whether it writes. Names no app user. */
+  me() {
+    return this.#transport.send(me());
+  }
+  /**
+   * The memory of one of your app users, by your own id for them: 1 to 35 letters, digits, `.`,
+   * `_` and `-`, beginning with a letter or digit. A RangeError otherwise, before any request.
+   */
+  user(id) {
+    return new User(this.#transport, checkedUserId(id), this.failOpen, this.#settings.log);
+  }
+  /** The app users of this key's project with memory, a page at a time in id order. */
+  users(options = {}) {
+    return this.#transport.send(users(options));
+  }
+  /** Every app user with memory, across pages. */
+  iterUsers(options = {}) {
+    return paged(
+      (cursor) => this.users({ ...options, cursor }),
+      (page) => page.users
+    );
+  }
+  /** Nothing to release: each request is its own. Here so code written for Python reads the same. */
+  close() {
+  }
+};
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+exports.SearchResult = SearchResult; exports.AlexeinError = AlexeinError; exports.AuthenticationError = AuthenticationError; exports.PermissionDeniedError = PermissionDeniedError; exports.NotFoundError = NotFoundError; exports.InvalidRequestError = InvalidRequestError; exports.RateLimitError = RateLimitError; exports.ServiceUnavailableError = ServiceUnavailableError; exports.APIConnectionError = APIConnectionError; exports.APITimeoutError = APITimeoutError; exports.VERSION = VERSION; exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL; exports.DEFAULT_TIMEOUT_MS = DEFAULT_TIMEOUT_MS; exports.DEFAULT_RETRIES = DEFAULT_RETRIES; exports.User = User; exports.Memory = Memory;