@infolang/sdk 0.2.0

package/dist/index.js

@@ -0,0 +1,748 @@
+import { readFile, writeFile } from 'fs/promises';
+import { homedir } from 'os';
+import { join } from 'path';
+
+// src/auth.ts
+
+// src/errors.ts
+var InfoLangError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = new.target.name;
+  }
+};
+var InfoLangConfigError = class extends InfoLangError {
+};
+var InfoLangConnectionError = class extends InfoLangError {
+};
+var InfoLangAPIError = class extends InfoLangError {
+  status;
+  body;
+  requestId;
+  constructor(message, options) {
+    const suffix = options.requestId ? ` (request_id=${options.requestId})` : "";
+    super(`${message}${suffix}`);
+    this.status = options.status;
+    this.body = options.body;
+    this.requestId = options.requestId;
+  }
+};
+var AuthenticationError = class extends InfoLangAPIError {
+};
+var NotFoundError = class extends InfoLangAPIError {
+};
+var ValidationError = class extends InfoLangAPIError {
+};
+var RateLimitError = class extends InfoLangAPIError {
+  retryAfter;
+  constructor(message, options) {
+    super(message, options);
+    this.retryAfter = options.retryAfter;
+  }
+};
+var ServerError = class extends InfoLangAPIError {
+};
+function messageFromBody(body) {
+  if (body && typeof body === "object") {
+    const record = body;
+    for (const key of ["error", "message", "detail"]) {
+      const value = record[key];
+      if (typeof value === "string" && value) return value;
+    }
+  }
+  if (typeof body === "string" && body) return body;
+  return void 0;
+}
+function errorFromResponse(options) {
+  const message = messageFromBody(options.body) ?? `InfoLang request failed with status ${options.status}`;
+  switch (true) {
+    case (options.status === 401 || options.status === 403):
+      return new AuthenticationError(message, options);
+    case options.status === 404:
+      return new NotFoundError(message, options);
+    case (options.status === 400 || options.status === 422):
+      return new ValidationError(message, options);
+    case options.status === 429:
+      return new RateLimitError(message, options);
+    case options.status >= 500:
+      return new ServerError(message, options);
+    default:
+      return new InfoLangAPIError(message, options);
+  }
+}
+
+// src/auth.ts
+var DEFAULT_SESSION_PATH = join(homedir(), ".config", "infolang", "session.json");
+var ApiKeyAuth = class {
+  constructor(apiKey) {
+    this.apiKey = apiKey;
+    if (!apiKey) throw new InfoLangConfigError("apiKey must not be empty");
+  }
+  apiKey;
+  async headers() {
+    return { Authorization: `Bearer ${this.apiKey}` };
+  }
+};
+var DevKeyAuth = class {
+  namespace;
+  token;
+  constructor(devKey) {
+    const idx = devKey.indexOf(":");
+    if (idx < 0) throw new InfoLangConfigError("dev key must be in 'key:namespace' form");
+    this.token = devKey.slice(0, idx);
+    this.namespace = devKey.slice(idx + 1);
+  }
+  async headers() {
+    return { Authorization: `Bearer ${this.token}` };
+  }
+};
+var SessionFileAuth = class {
+  constructor(path = DEFAULT_SESSION_PATH) {
+    this.path = path;
+  }
+  path;
+  cache;
+  async load() {
+    let raw;
+    try {
+      raw = await readFile(this.path, "utf8");
+    } catch {
+      throw new InfoLangConfigError(
+        `session file not found at ${this.path}; run 'npx @infolang/cursor-setup'`
+      );
+    }
+    try {
+      return JSON.parse(raw);
+    } catch {
+      throw new InfoLangConfigError(`session file at ${this.path} is not valid JSON`);
+    }
+  }
+  async headers() {
+    let session = this.cache ?? await this.load();
+    if (this.isExpired(session)) session = await this.refresh(session);
+    this.cache = session;
+    if (!session.access_token) {
+      throw new InfoLangConfigError("session file is missing 'access_token'");
+    }
+    return { Authorization: `Bearer ${session.access_token}` };
+  }
+  isExpired(session) {
+    if (typeof session.expires_at !== "number") return false;
+    return Date.now() / 1e3 >= session.expires_at - 30;
+  }
+  async refresh(session) {
+    if (!session.refresh_token || !session.token_url) return session;
+    const resp = await fetch(session.token_url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify({
+        grant_type: "refresh_token",
+        refresh_token: session.refresh_token
+      })
+    });
+    if (!resp.ok) return session;
+    const data = await resp.json();
+    const merged = { ...session, ...data };
+    if (typeof data.expires_in === "number") {
+      merged.expires_at = Date.now() / 1e3 + data.expires_in;
+    }
+    try {
+      await writeFile(this.path, JSON.stringify(merged));
+    } catch {
+    }
+    return merged;
+  }
+};
+var OriginAuth = class {
+  constructor(workspace, secret) {
+    this.workspace = workspace;
+    this.secret = secret;
+  }
+  workspace;
+  secret;
+  async headers() {
+    return {
+      "X-InfoLang-Workspace": this.workspace,
+      "X-InfoLang-Origin-Secret": this.secret
+    };
+  }
+};
+
+// src/resources/ops.ts
+function compact(payload) {
+  return Object.fromEntries(Object.entries(payload).filter(([, v]) => v !== void 0));
+}
+function buildRecall(query, opts) {
+  return {
+    method: "POST",
+    path: "/v1/recall",
+    body: compact({
+      query,
+      namespace: opts.namespace,
+      top_k: opts.topK,
+      filters: opts.filters,
+      verbose: opts.verbose
+    })
+  };
+}
+function hitToChunk(hit) {
+  return {
+    i: hit.id ?? hit.i,
+    t: hit.text ?? hit.t ?? "",
+    g: hit.tags ?? hit.g,
+    s: hit.similarity ?? hit.score ?? hit.s
+  };
+}
+function parseRecall(data, metering) {
+  const record = data && typeof data === "object" ? data : {};
+  const rawChunks = Array.isArray(record.chunks) ? record.chunks : Array.isArray(record.hits) ? record.hits.map((hit) => hitToChunk(hit)) : Array.isArray(data) ? data : [];
+  const chunks = rawChunks.map((c) => {
+    const item = c;
+    return {
+      id: String(item.i ?? item.id ?? ""),
+      score: typeof item.s === "number" ? item.s : item.score,
+      text: String(item.t ?? item.text ?? ""),
+      tags: item.g ?? item.tags
+    };
+  });
+  const top = chunks[0]?.score;
+  return {
+    chunks,
+    namespace: record.namespace,
+    metering,
+    weak: top !== void 0 && top < 0.85
+  };
+}
+function buildRemember(text, opts) {
+  return {
+    method: "POST",
+    path: "/v1/remember",
+    body: compact({ text, namespace: opts.namespace, source: opts.source, tags: opts.tags })
+  };
+}
+function parseRemember(data) {
+  const record = data && typeof data === "object" ? data : {};
+  return {
+    memoryId: record.id ?? record.memory_id,
+    namespace: record.namespace
+  };
+}
+function buildForget(memoryId, namespace) {
+  return {
+    method: "DELETE",
+    path: `/v1/memories/${encodeURIComponent(memoryId)}`
+  };
+}
+function buildListBanks() {
+  return { method: "GET", path: "/v1/banks" };
+}
+function parseBanks(data) {
+  const record = data;
+  const items = Array.isArray(data) ? data : Array.isArray(record?.banks) ? record.banks : [];
+  return items.map((b) => {
+    const item = b;
+    const count = typeof item.count === "number" ? item.count : typeof item.total_memories === "number" ? item.total_memories : void 0;
+    return {
+      namespace: String(item.namespace ?? ""),
+      count
+    };
+  });
+}
+function buildListRecent(opts) {
+  const params = new URLSearchParams();
+  if (opts.namespace) params.set("namespace", opts.namespace);
+  if (opts.n !== void 0) params.set("limit", String(opts.n));
+  const query = params.toString();
+  return { method: "GET", path: `/v1/memories${query ? `?${query}` : ""}` };
+}
+function buildContextPack(query, opts) {
+  return {
+    method: "POST",
+    path: "/v1/context-pack",
+    body: compact({
+      query,
+      namespace: opts.namespace,
+      max_tokens: opts.maxTokens,
+      repo_root: opts.repoRoot
+    })
+  };
+}
+function parseContextPack(data, metering) {
+  const record = data && typeof data === "object" ? data : {};
+  return {
+    pack: String(record.pack ?? record.context ?? record.text ?? data ?? ""),
+    tokensEstimated: record.tokens_estimated,
+    namespace: record.namespace,
+    metering
+  };
+}
+function buildIngestRepo(namespace, opts) {
+  return {
+    method: "POST",
+    path: `/v1/repos/${encodeURIComponent(namespace)}/ingest`,
+    body: compact({ repo_root: opts.repoRoot, ref: opts.ref })
+  };
+}
+function buildExecute(operations) {
+  return { method: "POST", path: "/v1/execute", body: { operations } };
+}
+function buildHealth() {
+  return { method: "GET", path: "/v1/health" };
+}
+function filterHitsByTags(chunks, tagFilter, topK) {
+  let ordered = chunks;
+  if (tagFilter && tagFilter.length > 0) {
+    const wanted = new Set(
+      tagFilter.map((t) => t.trim().toLowerCase()).filter(Boolean)
+    );
+    const matches = (chunk) => {
+      if (!chunk.tags) return false;
+      const have = new Set(
+        chunk.tags.split(",").map((t) => t.trim().toLowerCase()).filter(Boolean)
+      );
+      for (const t of wanted) {
+        if (have.has(t)) return true;
+      }
+      return false;
+    };
+    ordered = [...chunks.filter(matches), ...chunks.filter((c) => !matches(c))];
+  }
+  return topK !== void 0 ? ordered.slice(0, topK) : ordered;
+}
+function buildRememberBatch(items, opts) {
+  const batchItems = items.map(
+    (item) => compact({
+      text: item.text,
+      source: item.source ?? opts.source,
+      tags: item.tags
+    })
+  );
+  return buildExecute([
+    {
+      op: "remember_batch",
+      args: compact({
+        items: batchItems,
+        namespace: opts.namespace,
+        source: opts.source
+      })
+    }
+  ]);
+}
+function parseExecuteRememberBatch(data) {
+  const record = data;
+  const results = Array.isArray(record?.results) ? record.results : [];
+  const out = [];
+  for (const result of results) {
+    const payload = result?.payload;
+    const inner = Array.isArray(payload?.results) ? payload.results : null;
+    if (inner) {
+      for (const r of inner) {
+        out.push(parseRemember(r));
+      }
+    } else {
+      out.push(parseRemember(payload ?? {}));
+    }
+  }
+  return out;
+}
+function normalizeRememberItems(items, defaultSource) {
+  return items.map((item) => {
+    if (typeof item === "string") {
+      return { text: item, source: defaultSource };
+    }
+    if (item && typeof item === "object" && typeof item.text === "string") {
+      return item;
+    }
+    throw new TypeError("rememberBatch items must be string or { text } object");
+  });
+}
+
+// src/resources/context.ts
+var ContextResource = class {
+  constructor(transport, defaultNamespace) {
+    this.transport = transport;
+    this.defaultNamespace = defaultNamespace;
+  }
+  transport;
+  defaultNamespace;
+  async contextPack(query, options = {}) {
+    const namespace = options.namespace ?? this.defaultNamespace;
+    if (!namespace) {
+      throw new InfoLangConfigError(
+        "contextPack requires a namespace (set one on the client or pass it)"
+      );
+    }
+    const { data, metering } = await this.transport.request(
+      buildContextPack(query, {
+        namespace,
+        maxTokens: options.maxTokens,
+        repoRoot: options.repoRoot
+      })
+    );
+    return parseContextPack(data, metering);
+  }
+  async ingestRepo(namespace, options) {
+    const { data } = await this.transport.request(
+      buildIngestRepo(namespace, options)
+    );
+    return data && typeof data === "object" ? data : { result: data };
+  }
+  async execute(operations) {
+    const { data } = await this.transport.request(buildExecute(operations));
+    return data && typeof data === "object" ? data : { results: data };
+  }
+};
+
+// src/resources/health.ts
+var HealthResource = class {
+  constructor(transport) {
+    this.transport = transport;
+  }
+  transport;
+  async check() {
+    const { data } = await this.transport.request(buildHealth());
+    return data && typeof data === "object" ? data : { status: data };
+  }
+};
+
+// src/resources/memory.ts
+var MemoryResource = class {
+  constructor(transport, defaultNamespace) {
+    this.transport = transport;
+    this.defaultNamespace = defaultNamespace;
+  }
+  transport;
+  defaultNamespace;
+  async recall(query, options = {}) {
+    const { data, metering } = await this.transport.request(
+      buildRecall(query, {
+        namespace: options.namespace ?? this.defaultNamespace,
+        topK: options.topK,
+        filters: options.filters,
+        verbose: options.verbose
+      })
+    );
+    return parseRecall(data, metering);
+  }
+  /** Agent-style recall with a sensible default `topK` of 5. */
+  async investigate(query, options = {}) {
+    return this.recall(query, {
+      namespace: options.namespaceHint,
+      topK: options.topK ?? 5
+    });
+  }
+  async remember(text, options = {}) {
+    const { data } = await this.transport.request(
+      buildRemember(text, {
+        namespace: options.namespace ?? this.defaultNamespace,
+        source: options.source,
+        tags: options.tags
+      })
+    );
+    return parseRemember(data);
+  }
+  /** Alias for `remember` matching the `auto_memorize` tool. */
+  async memorize(content, options = {}) {
+    return this.remember(content, options);
+  }
+  async forget(memoryId, options = {}) {
+    await this.transport.request(
+      buildForget(memoryId, options.namespace ?? this.defaultNamespace)
+    );
+  }
+  async listBanks() {
+    const { data } = await this.transport.request(buildListBanks());
+    return parseBanks(data);
+  }
+  async listRecent(options = {}) {
+    const { data } = await this.transport.request(
+      buildListRecent({ namespace: options.namespace ?? this.defaultNamespace, n: options.n })
+    );
+    if (Array.isArray(data)) return data;
+    const record = data;
+    return Array.isArray(record?.memories) ? record.memories : [];
+  }
+  /** Recall with tag-inclusion ordering over a candidate pool (client-side). */
+  async recallHybrid(query, options = {}) {
+    void options.useHybrid;
+    const ns = options.namespace ?? this.defaultNamespace;
+    const topK = options.topK ?? 10;
+    const pool = Math.max(options.candidatePool ?? 0, topK) || topK;
+    const result = await this.recall(query, { namespace: ns, topK: pool });
+    result.chunks = filterHitsByTags(result.chunks, options.tagFilter, topK);
+    return result;
+  }
+  /** Store many memories via POST /v1/execute remember_batch. */
+  async rememberBatch(items, options = {}) {
+    if (!items.length) return [];
+    const records = normalizeRememberItems(items, options.source);
+    const { data } = await this.transport.request(
+      buildRememberBatch(records, {
+        namespace: options.namespace ?? this.defaultNamespace,
+        source: options.source
+      })
+    );
+    return parseExecuteRememberBatch(data);
+  }
+  /** Best-effort bulk clear (list + forget loop). */
+  async resetNamespace(namespace, options = {}) {
+    const ns = namespace ?? this.defaultNamespace;
+    const batch = options.batch ?? 500;
+    let deleted = 0;
+    while (true) {
+      const recent = await this.listRecent({ namespace: ns, n: batch });
+      const ids = recent.map((r) => {
+        if (!r || typeof r !== "object") return null;
+        const row = r;
+        for (const key of ["id", "memory_id", "i"]) {
+          const v = row[key];
+          if (typeof v === "string" && v) return v;
+        }
+        return null;
+      }).filter((id) => Boolean(id));
+      if (!ids.length) break;
+      for (const id of ids) {
+        await this.forget(id, { namespace: ns });
+        deleted += 1;
+      }
+      if (ids.length < batch) break;
+    }
+    return deleted;
+  }
+};
+
+// src/transport.ts
+var RETRY_STATUSES = /* @__PURE__ */ new Set([429, 500, 502, 503, 504]);
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function parseMetering(headers) {
+  const num = (name) => {
+    const raw = headers.get(name);
+    if (raw == null) return void 0;
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : void 0;
+  };
+  return {
+    tokensSaved: num("x-infolang-tokens-saved"),
+    chunksUsed: num("x-infolang-chunks-used"),
+    repoCoverage: num("x-infolang-repo-coverage"),
+    requestId: headers.get("x-request-id") ?? void 0
+  };
+}
+function retryAfter(headers) {
+  const raw = headers.get("retry-after");
+  if (!raw) return void 0;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : void 0;
+}
+var Transport = class {
+  baseUrl;
+  auth;
+  fetchImpl;
+  timeoutMs;
+  maxRetries;
+  backoffBaseMs;
+  backoffCapMs;
+  userAgent;
+  workspaceId;
+  constructor(options) {
+    this.baseUrl = options.baseUrl.replace(/\/$/, "");
+    this.auth = options.auth;
+    this.fetchImpl = options.fetch ?? globalThis.fetch;
+    this.timeoutMs = options.timeoutMs ?? 3e4;
+    this.maxRetries = options.maxRetries ?? 2;
+    this.backoffBaseMs = options.backoffBaseMs ?? 500;
+    this.backoffCapMs = options.backoffCapMs ?? 8e3;
+    this.userAgent = options.userAgent;
+    this.workspaceId = options.workspaceId;
+    if (!this.fetchImpl) {
+      throw new InfoLangConnectionError(
+        "global fetch is unavailable; pass a fetch implementation via the client options"
+      );
+    }
+  }
+  delay(attempt, retryAfterSec) {
+    if (retryAfterSec != null) return retryAfterSec * 1e3;
+    const window = Math.min(this.backoffCapMs, this.backoffBaseMs * 2 ** attempt);
+    return Math.random() * window;
+  }
+  async request(options) {
+    const url = `${this.baseUrl}${options.path}`;
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+      const headers = {
+        "User-Agent": this.userAgent,
+        Accept: "application/json",
+        ...await this.auth.headers(),
+        ...options.headers
+      };
+      if (this.workspaceId) {
+        headers["X-InfoLang-Workspace-Id"] = this.workspaceId;
+      }
+      if (options.body !== void 0) headers["Content-Type"] = "application/json";
+      let response;
+      try {
+        response = await this.fetchImpl(url, {
+          method: options.method,
+          headers,
+          body: options.body !== void 0 ? JSON.stringify(options.body) : void 0,
+          signal: controller.signal
+        });
+      } catch (err) {
+        lastError = err;
+        clearTimeout(timer);
+        if (attempt >= this.maxRetries) {
+          throw new InfoLangConnectionError(
+            err instanceof Error ? err.message : "request failed"
+          );
+        }
+        await sleep(this.delay(attempt));
+        continue;
+      } finally {
+        clearTimeout(timer);
+      }
+      if (RETRY_STATUSES.has(response.status) && attempt < this.maxRetries) {
+        await sleep(this.delay(attempt, retryAfter(response.headers)));
+        continue;
+      }
+      return this.finish(response);
+    }
+    throw new InfoLangConnectionError(
+      lastError instanceof Error ? lastError.message : "request failed after retries"
+    );
+  }
+  async finish(response) {
+    const metering = parseMetering(response.headers);
+    const text = await response.text();
+    let data = text;
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+    if (response.ok) return { data, metering };
+    throw errorFromResponse({
+      status: response.status,
+      body: data,
+      requestId: metering.requestId,
+      retryAfter: retryAfter(response.headers)
+    });
+  }
+};
+
+// src/version.ts
+var version = "0.2.0";
+
+// src/client.ts
+var CLOUD_BASE_URL = "https://api.infolang.ai";
+var DIRECT_BASE_URL = "http://127.0.0.1:8766";
+function resolveAuth(options) {
+  if (options.auth) return options.auth;
+  if (options.apiKey) return new ApiKeyAuth(options.apiKey);
+  if (options.devKey) return new DevKeyAuth(options.devKey);
+  const envKey = globalThis.process?.env?.INFOLANG_API_KEY;
+  if (envKey) return new ApiKeyAuth(envKey);
+  const envDev = globalThis.process?.env?.INFOLANG_DEV_KEY;
+  if (envDev) return new DevKeyAuth(envDev);
+  throw new InfoLangConfigError(
+    "No credentials. Pass apiKey, devKey, or auth, set INFOLANG_API_KEY, or use InfoLang.fromSessionFile()."
+  );
+}
+function resolveBaseUrl(options, auth) {
+  if (options.baseUrl) return options.baseUrl;
+  const envUrl = globalThis.process?.env?.INFOLANG_BASE_URL;
+  if (envUrl) return envUrl;
+  return auth instanceof DevKeyAuth ? DIRECT_BASE_URL : CLOUD_BASE_URL;
+}
+function resolveNamespace(options, auth) {
+  if (options.namespace) return options.namespace;
+  if (auth instanceof DevKeyAuth) return auth.namespace;
+  return globalThis.process?.env?.INFOLANG_NAMESPACE;
+}
+function resolveWorkspace(options) {
+  if (options.workspace) return options.workspace;
+  return globalThis.process?.env?.INFOLANG_WORKSPACE ?? globalThis.process?.env?.INFOLANG_WORKSPACE_ID;
+}
+var InfoLang = class _InfoLang {
+  namespace;
+  workspace;
+  baseUrl;
+  memory;
+  context;
+  health;
+  constructor(options = {}) {
+    const auth = resolveAuth(options);
+    this.baseUrl = resolveBaseUrl(options, auth);
+    this.namespace = resolveNamespace(options, auth);
+    this.workspace = resolveWorkspace(options);
+    const transport = new Transport({
+      baseUrl: this.baseUrl,
+      auth,
+      fetch: options.fetch,
+      timeoutMs: options.timeoutMs,
+      maxRetries: options.maxRetries,
+      userAgent: `infolang-typescript/${version}`,
+      workspaceId: this.workspace
+    });
+    this.memory = new MemoryResource(transport, this.namespace);
+    this.context = new ContextResource(transport, this.namespace);
+    this.health = new HealthResource(transport);
+  }
+  // --- constructors ---------------------------------------------------
+  static fromApiKey(apiKey, options = {}) {
+    return new _InfoLang({ ...options, apiKey });
+  }
+  static fromDevKey(devKey, options = {}) {
+    return new _InfoLang({ ...options, devKey });
+  }
+  static fromSessionFile(path, options = {}) {
+    return new _InfoLang({ ...options, auth: new SessionFileAuth(path) });
+  }
+  // --- top-level aliases ----------------------------------------------
+  recall(query, options) {
+    return this.memory.recall(query, options);
+  }
+  investigate(query, options) {
+    return this.memory.investigate(query, options);
+  }
+  remember(text, options) {
+    return this.memory.remember(text, options);
+  }
+  memorize(content, options) {
+    return this.memory.memorize(content, options);
+  }
+  forget(memoryId, options) {
+    return this.memory.forget(memoryId, options);
+  }
+  listBanks() {
+    return this.memory.listBanks();
+  }
+  listRecent(options) {
+    return this.memory.listRecent(options);
+  }
+  recallHybrid(query, options) {
+    return this.memory.recallHybrid(query, options);
+  }
+  rememberBatch(items, options) {
+    return this.memory.rememberBatch(items, options);
+  }
+  resetNamespace(namespace, options) {
+    return this.memory.resetNamespace(namespace, options);
+  }
+  contextPack(query, options) {
+    return this.context.contextPack(query, options);
+  }
+  ingestRepo(namespace, options) {
+    return this.context.ingestRepo(namespace, options);
+  }
+  execute(operations) {
+    return this.context.execute(operations);
+  }
+};
+
+export { ApiKeyAuth, AuthenticationError, CLOUD_BASE_URL, DEFAULT_SESSION_PATH, DIRECT_BASE_URL, DevKeyAuth, InfoLang, InfoLangAPIError, InfoLangConfigError, InfoLangConnectionError, InfoLangError, NotFoundError, OriginAuth, RateLimitError, ServerError, SessionFileAuth, ValidationError, version };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map