@babav/knowledge-core-client 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -11,6 +11,14 @@
  * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient with a TENANT
  * key for all data ops; use AdminClient with the ADMIN key for tenant / API-key /
  * agent management. The key is server-side only — never ship it to a browser.
+ *
+ * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
+ *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
+ *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
+ * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
+ * (the app is then responsible for supplying it). A missing value (no param AND no
+ * env var) throws at construction with a clear message. In Deno, env access needs
+ * `--allow-env` (without it, pass the values explicitly).
  */
 export type UUID = string;
 export interface Page<T> {
@@ -196,10 +204,12 @@ export declare class KnowledgeCoreError extends Error {
     get code(): string | undefined;
 }
 export interface ClientOptions {
-    baseUrl: string;
-    apiKey: string;
-    /** Optional default fetch timeout (ms). Streaming ignores this. Note:
-     *  synchronous ingest can take a while — set this generously or omit. */
+    /** API base URL. Defaults to env BABAV_KC_BASE_URL when omitted. */
+    baseUrl?: string;
+    /** Tenant key (KnowledgeCoreClient) or admin key (AdminClient). Defaults to env
+     *  BABAV_KC_TENANT_KEY / BABAV_KC_ADMIN_KEY respectively when omitted. */
+    apiKey?: string;
+    /** Optional default fetch timeout (ms). Streaming ignores this. */
     timeoutMs?: number;
     fetch?: typeof fetch;
 }
@@ -215,7 +225,7 @@ declare class HttpBase {
     protected readonly apiKey: string;
     protected readonly timeoutMs?: number;
     protected readonly _fetch: typeof fetch;
-    constructor(opts: ClientOptions);
+    constructor(opts?: ClientOptions, keyEnvVar?: string);
     protected url(path: string, query?: RequestOpts["query"]): string;
     protected raw(method: string, path: string, opts?: RequestOpts): Promise<Response>;
     protected request<T>(method: string, path: string, opts?: RequestOpts): Promise<T>;
@@ -240,6 +250,8 @@ export interface StreamHandlers {
     onEvent?: (event: string, data: unknown) => void;
 }
 export declare class KnowledgeCoreClient extends HttpBase {
+    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
+    constructor(opts?: ClientOptions);
     query(agentId: UUID, body: QueryRequest): Promise<QueryResponse>;
     /** Streaming query (SSE). Resolves when the stream ends. */
     queryStream(agentId: UUID, body: QueryRequest, handlers: StreamHandlers, signal?: AbortSignal): Promise<void>;
@@ -276,6 +288,11 @@ export declare class KnowledgeCoreClient extends HttpBase {
         }) => Promise<Page<Document>>;
         /** Count documents in the corpus: { total, indexed, in_flight, failed }. */
         countDocuments: (id: UUID) => Promise<DocumentCount>;
+        /** Documents in the corpus whose filename contains `q` (case-insensitive), paginated. */
+        searchDocuments: (id: UUID, q: string, opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Document>>;
         /** Upload a file and ingest it ASYNCHRONOUSLY — resolves with the created
          *  document at status `pending` (HTTP 202); track via documents.get() polling
          *  the status to `indexed`/`failed`, or the tenant result webhook. */
@@ -305,6 +322,11 @@ export declare class KnowledgeCoreClient extends HttpBase {
         }) => Promise<Page<Document>>;
         /** Count documents in the folder: { total, indexed, in_flight, failed }. */
         countDocuments: (folderId: UUID) => Promise<DocumentCount>;
+        /** Documents in the folder whose filename contains `q` (case-insensitive), paginated. */
+        searchDocuments: (folderId: UUID, q: string, opts?: {
+            limit?: number;
+            cursor?: string;
+        }) => Promise<Page<Document>>;
     };
     documents: {
         get: (id: UUID) => Promise<Document>;
@@ -386,6 +408,8 @@ export declare class KnowledgeCoreClient extends HttpBase {
     };
 }
 export declare class AdminClient extends HttpBase {
+    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
+    constructor(opts?: ClientOptions);
     tenants: {
         create: (b: Partial<Tenant> & {
             name: string;

package/dist/index.js

@@ -11,6 +11,14 @@
  * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient with a TENANT
  * key for all data ops; use AdminClient with the ADMIN key for tenant / API-key /
  * agent management. The key is server-side only — never ship it to a browser.
+ *
+ * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
+ *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
+ *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
+ * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
+ * (the app is then responsible for supplying it). A missing value (no param AND no
+ * env var) throws at construction with a clear message. In Deno, env access needs
+ * `--allow-env` (without it, pass the values explicitly).
  */
 // ---------------------------------------------------------------------------
 // Errors
@@ -35,14 +43,37 @@ export class KnowledgeCoreError extends Error {
         return d?.detail?.error ?? d?.error;
     }
 }
+/** Read an env var under Node (process.env) or Deno (Deno.env); undefined if unset
+ *  or inaccessible (e.g. Deno without --allow-env). */
+function readEnv(name) {
+    const g = globalThis;
+    const fromNode = g.process?.env?.[name];
+    if (fromNode)
+        return fromNode;
+    try {
+        const fromDeno = g.Deno?.env?.get?.(name);
+        if (fromDeno)
+            return fromDeno;
+    }
+    catch {
+        /* Deno env access denied (no --allow-env) — treat as unset */
+    }
+    return undefined;
+}
 class HttpBase {
     baseUrl;
     apiKey;
     timeoutMs;
     _fetch;
-    constructor(opts) {
-        this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-        this.apiKey = opts.apiKey;
+    constructor(opts = {}, keyEnvVar = "BABAV_KC_TENANT_KEY") {
+        const baseUrl = opts.baseUrl ?? readEnv("BABAV_KC_BASE_URL");
+        const apiKey = opts.apiKey ?? readEnv(keyEnvVar);
+        if (!baseUrl)
+            throw new Error("KnowledgeCore: no base URL — pass { baseUrl } or set BABAV_KC_BASE_URL");
+        if (!apiKey)
+            throw new Error(`KnowledgeCore: no API key — pass { apiKey } or set ${keyEnvVar}`);
+        this.baseUrl = baseUrl.replace(/\/+$/, "");
+        this.apiKey = apiKey;
         this.timeoutMs = opts.timeoutMs;
         this._fetch = opts.fetch ?? fetch;
     }
@@ -121,6 +152,10 @@ function toBlob(data, contentType) {
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
 export class KnowledgeCoreClient extends HttpBase {
+    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
+    constructor(opts = {}) {
+        super(opts, "BABAV_KC_TENANT_KEY");
+    }
     // --- query (agent-anchored) ---
     query(agentId, body) {
         return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
@@ -166,6 +201,8 @@ export class KnowledgeCoreClient extends HttpBase {
         listDocuments: (id, q) => this.request("GET", `/v1/corpora/${id}/documents`, { query: q }),
         /** Count documents in the corpus: { total, indexed, in_flight, failed }. */
         countDocuments: (id) => this.request("GET", `/v1/corpora/${id}/documents/count`),
+        /** Documents in the corpus whose filename contains `q` (case-insensitive), paginated. */
+        searchDocuments: (id, q, opts) => this.request("GET", `/v1/corpora/${id}/documents/search`, { query: { q, ...opts } }),
         /** Upload a file and ingest it ASYNCHRONOUSLY — resolves with the created
          *  document at status `pending` (HTTP 202); track via documents.get() polling
          *  the status to `indexed`/`failed`, or the tenant result webhook. */
@@ -195,6 +232,8 @@ export class KnowledgeCoreClient extends HttpBase {
         listDocuments: (folderId, q) => this.request("GET", `/v1/folders/${folderId}/documents`, { query: q }),
         /** Count documents in the folder: { total, indexed, in_flight, failed }. */
         countDocuments: (folderId) => this.request("GET", `/v1/folders/${folderId}/documents/count`),
+        /** Documents in the folder whose filename contains `q` (case-insensitive), paginated. */
+        searchDocuments: (folderId, q, opts) => this.request("GET", `/v1/folders/${folderId}/documents/search`, { query: { q, ...opts } }),
     };
     // --- documents ---
     documents = {
@@ -253,6 +292,10 @@ export class KnowledgeCoreClient extends HttpBase {
 // Admin client (tenant + key + agent management) — use the ADMIN key
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
+    /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
+    constructor(opts = {}) {
+        super(opts, "BABAV_KC_ADMIN_KEY");
+    }
     tenants = {
         create: (b) => this.request("POST", "/v1/tenants", { json: b }),
         list: (q) => this.request("GET", "/v1/tenants", { query: q }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@babav/knowledge-core-client",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "TypeScript client for the Babav Knowledge Core API (Deno + Node 18+, zero deps).",
   "type": "module",
   "main": "./dist/index.js",

package/src/index.ts

@@ -11,6 +11,14 @@
  * Auth: every call carries an X-API-Key. Use KnowledgeCoreClient with a TENANT
  * key for all data ops; use AdminClient with the ADMIN key for tenant / API-key /
  * agent management. The key is server-side only — never ship it to a browser.
+ *
+ * Configuration — environment variables (Node `process.env` or Deno `Deno.env`):
+ *   `new KnowledgeCoreClient()`  reads BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY
+ *   `new AdminClient()`          reads BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY
+ * Passing { baseUrl } / { apiKey } explicitly overrides the env var for that field
+ * (the app is then responsible for supplying it). A missing value (no param AND no
+ * env var) throws at construction with a clear message. In Deno, env access needs
+ * `--allow-env` (without it, pass the values explicitly).
  */
 
 // ---------------------------------------------------------------------------
@@ -225,14 +233,34 @@ export class KnowledgeCoreError extends Error {
 // Base HTTP
 // ---------------------------------------------------------------------------
 export interface ClientOptions {
-  baseUrl: string;
-  apiKey: string;
-  /** Optional default fetch timeout (ms). Streaming ignores this. Note:
-   *  synchronous ingest can take a while — set this generously or omit. */
+  /** API base URL. Defaults to env BABAV_KC_BASE_URL when omitted. */
+  baseUrl?: string;
+  /** Tenant key (KnowledgeCoreClient) or admin key (AdminClient). Defaults to env
+   *  BABAV_KC_TENANT_KEY / BABAV_KC_ADMIN_KEY respectively when omitted. */
+  apiKey?: string;
+  /** Optional default fetch timeout (ms). Streaming ignores this. */
   timeoutMs?: number;
   fetch?: typeof fetch; // override for tests
 }
 
+/** Read an env var under Node (process.env) or Deno (Deno.env); undefined if unset
+ *  or inaccessible (e.g. Deno without --allow-env). */
+function readEnv(name: string): string | undefined {
+  const g = globalThis as {
+    process?: { env?: Record<string, string | undefined> };
+    Deno?: { env?: { get?: (n: string) => string | undefined } };
+  };
+  const fromNode = g.process?.env?.[name];
+  if (fromNode) return fromNode;
+  try {
+    const fromDeno = g.Deno?.env?.get?.(name);
+    if (fromDeno) return fromDeno;
+  } catch {
+    /* Deno env access denied (no --allow-env) — treat as unset */
+  }
+  return undefined;
+}
+
 interface RequestOpts {
   query?: Record<string, string | number | boolean | undefined>;
   json?: unknown;
@@ -247,9 +275,13 @@ class HttpBase {
   protected readonly timeoutMs?: number;
   protected readonly _fetch: typeof fetch;
 
-  constructor(opts: ClientOptions) {
-    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
-    this.apiKey = opts.apiKey;
+  constructor(opts: ClientOptions = {}, keyEnvVar = "BABAV_KC_TENANT_KEY") {
+    const baseUrl = opts.baseUrl ?? readEnv("BABAV_KC_BASE_URL");
+    const apiKey = opts.apiKey ?? readEnv(keyEnvVar);
+    if (!baseUrl) throw new Error("KnowledgeCore: no base URL — pass { baseUrl } or set BABAV_KC_BASE_URL");
+    if (!apiKey) throw new Error(`KnowledgeCore: no API key — pass { apiKey } or set ${keyEnvVar}`);
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.apiKey = apiKey;
     this.timeoutMs = opts.timeoutMs;
     this._fetch = opts.fetch ?? fetch;
   }
@@ -342,6 +374,11 @@ export interface StreamHandlers {
 // Tenant client (data ops) — use a TENANT key
 // ---------------------------------------------------------------------------
 export class KnowledgeCoreClient extends HttpBase {
+  /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_TENANT_KEY when not passed. */
+  constructor(opts: ClientOptions = {}) {
+    super(opts, "BABAV_KC_TENANT_KEY");
+  }
+
   // --- query (agent-anchored) ---
   query(agentId: UUID, body: QueryRequest): Promise<QueryResponse> {
     return this.request("POST", `/v1/agents/${agentId}/query`, { json: body });
@@ -392,6 +429,9 @@ export class KnowledgeCoreClient extends HttpBase {
     /** Count documents in the corpus: { total, indexed, in_flight, failed }. */
     countDocuments: (id: UUID) =>
       this.request<DocumentCount>("GET", `/v1/corpora/${id}/documents/count`),
+    /** Documents in the corpus whose filename contains `q` (case-insensitive), paginated. */
+    searchDocuments: (id: UUID, q: string, opts?: { limit?: number; cursor?: string }) =>
+      this.request<Page<Document>>("GET", `/v1/corpora/${id}/documents/search`, { query: { q, ...opts } }),
     /** Upload a file and ingest it ASYNCHRONOUSLY — resolves with the created
      *  document at status `pending` (HTTP 202); track via documents.get() polling
      *  the status to `indexed`/`failed`, or the tenant result webhook. */
@@ -422,6 +462,9 @@ export class KnowledgeCoreClient extends HttpBase {
     /** Count documents in the folder: { total, indexed, in_flight, failed }. */
     countDocuments: (folderId: UUID) =>
       this.request<DocumentCount>("GET", `/v1/folders/${folderId}/documents/count`),
+    /** Documents in the folder whose filename contains `q` (case-insensitive), paginated. */
+    searchDocuments: (folderId: UUID, q: string, opts?: { limit?: number; cursor?: string }) =>
+      this.request<Page<Document>>("GET", `/v1/folders/${folderId}/documents/search`, { query: { q, ...opts } }),
   };
 
   // --- documents ---
@@ -495,6 +538,11 @@ export class KnowledgeCoreClient extends HttpBase {
 // Admin client (tenant + key + agent management) — use the ADMIN key
 // ---------------------------------------------------------------------------
 export class AdminClient extends HttpBase {
+  /** Defaults to env BABAV_KC_BASE_URL + BABAV_KC_ADMIN_KEY when not passed. */
+  constructor(opts: ClientOptions = {}) {
+    super(opts, "BABAV_KC_ADMIN_KEY");
+  }
+
   tenants = {
     create: (b: Partial<Tenant> & { name: string }) => this.request<Tenant>("POST", "/v1/tenants", { json: b }),
     list: (q?: { limit?: number; cursor?: string }) => this.request<Page<Tenant>>("GET", "/v1/tenants", { query: q }),