@babav/knowledge-core-client 0.4.0 → 0.6.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> {
@@ -116,6 +124,14 @@ export interface DocumentCount {
     in_flight: number;
     failed: number;
 }
+/** A signed PUT URL for uploading a large file straight to GCS + the pre-allocated
+ *  document id to reference on from-upload. */
+export interface UploadUrl {
+    upload_url: string;
+    document_id: UUID;
+    gcs_uri: string;
+    expires_in: number;
+}
 export interface Conversation {
     id: UUID;
     title: string | null;
@@ -196,10 +212,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 +233,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 +258,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>;
@@ -292,6 +312,32 @@ export declare class KnowledgeCoreClient extends HttpBase {
             folder_id?: UUID;
             custom_metadata?: Record<string, unknown>;
         }) => Promise<Document>;
+        /** Mint a signed PUT URL to upload a large file straight to GCS (bypasses the
+         *  ~32 MB request limit). PUT the bytes to upload_url, then ingestFromUpload. */
+        uploadUrl: (id: UUID, a: {
+            filename: string;
+            content_type?: string;
+        }) => Promise<UploadUrl>;
+        /** Ingest a file already PUT to GCS via uploadUrl. Resolves with the `pending`
+         *  document (202); track via documents.get() / webhook. */
+        ingestFromUpload: (id: UUID, a: {
+            document_id: UUID;
+            filename: string;
+            content_type?: string;
+            visibility?: Visibility;
+            folder_id?: UUID;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<Document>;
+        /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
+         *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
+        uploadDocument: (id: UUID, a: {
+            file: FileData;
+            filename: string;
+            content_type?: string;
+            visibility?: Visibility;
+            folder_id?: UUID;
+            custom_metadata?: Record<string, unknown>;
+        }) => Promise<Document>;
     };
     parse(a: {
         file: FileData;
@@ -396,6 +442,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 });
@@ -182,6 +217,29 @@ export class KnowledgeCoreClient extends HttpBase {
                 fd.append("folder_id", a.folder_id);
             return this.request("POST", `/v1/corpora/${id}/documents`, { body: fd });
         },
+        /** Mint a signed PUT URL to upload a large file straight to GCS (bypasses the
+         *  ~32 MB request limit). PUT the bytes to upload_url, then ingestFromUpload. */
+        uploadUrl: (id, a) => this.request("POST", `/v1/corpora/${id}/documents/upload-url`, { json: a }),
+        /** Ingest a file already PUT to GCS via uploadUrl. Resolves with the `pending`
+         *  document (202); track via documents.get() / webhook. */
+        ingestFromUpload: (id, a) => this.request("POST", `/v1/corpora/${id}/documents/from-upload`, { json: a }),
+        /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
+         *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
+        uploadDocument: async (id, a) => {
+            const u = await this.corpora.uploadUrl(id, { filename: a.filename, content_type: a.content_type });
+            const put = await this._fetch(u.upload_url, {
+                method: "PUT",
+                body: toBlob(a.file, a.content_type),
+                headers: a.content_type ? { "content-type": a.content_type } : {},
+            });
+            if (!put.ok) {
+                throw new KnowledgeCoreError(put.status, safeJson(await put.text()), u.upload_url);
+            }
+            return this.corpora.ingestFromUpload(id, {
+                document_id: u.document_id, filename: a.filename, content_type: a.content_type,
+                visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
+            });
+        },
     };
     // --- parsing (utility: file -> text, stores nothing) ---
     parse(a) {
@@ -257,6 +315,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.4.0",
+  "version": "0.6.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).
  */
 
 // ---------------------------------------------------------------------------
@@ -130,6 +138,14 @@ export interface DocumentCount {
   in_flight: number;
   failed: number;
 }
+/** A signed PUT URL for uploading a large file straight to GCS + the pre-allocated
+ *  document id to reference on from-upload. */
+export interface UploadUrl {
+  upload_url: string;
+  document_id: UUID;
+  gcs_uri: string;
+  expires_in: number;
+}
 export interface Conversation {
   id: UUID;
   title: string | null;
@@ -225,14 +241,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 +283,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 +382,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 });
@@ -406,6 +451,31 @@ export class KnowledgeCoreClient extends HttpBase {
       if (a.folder_id) fd.append("folder_id", a.folder_id);
       return this.request<Document>("POST", `/v1/corpora/${id}/documents`, { body: fd });
     },
+    /** Mint a signed PUT URL to upload a large file straight to GCS (bypasses the
+     *  ~32 MB request limit). PUT the bytes to upload_url, then ingestFromUpload. */
+    uploadUrl: (id: UUID, a: { filename: string; content_type?: string }) =>
+      this.request<UploadUrl>("POST", `/v1/corpora/${id}/documents/upload-url`, { json: a }),
+    /** Ingest a file already PUT to GCS via uploadUrl. Resolves with the `pending`
+     *  document (202); track via documents.get() / webhook. */
+    ingestFromUpload: (id: UUID, a: { document_id: UUID; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }) =>
+      this.request<Document>("POST", `/v1/corpora/${id}/documents/from-upload`, { json: a }),
+    /** Convenience for LARGE files: uploadUrl → PUT the bytes to GCS → ingestFromUpload.
+     *  Use this instead of ingestDocument when the file may exceed ~32 MB. */
+    uploadDocument: async (id: UUID, a: { file: FileData; filename: string; content_type?: string; visibility?: Visibility; folder_id?: UUID; custom_metadata?: Record<string, unknown> }): Promise<Document> => {
+      const u = await this.corpora.uploadUrl(id, { filename: a.filename, content_type: a.content_type });
+      const put = await this._fetch(u.upload_url, {
+        method: "PUT",
+        body: toBlob(a.file, a.content_type),
+        headers: a.content_type ? { "content-type": a.content_type } : {},
+      });
+      if (!put.ok) {
+        throw new KnowledgeCoreError(put.status, safeJson(await put.text()), u.upload_url);
+      }
+      return this.corpora.ingestFromUpload(id, {
+        document_id: u.document_id, filename: a.filename, content_type: a.content_type,
+        visibility: a.visibility, folder_id: a.folder_id, custom_metadata: a.custom_metadata,
+      });
+    },
   };
 
   // --- parsing (utility: file -> text, stores nothing) ---
@@ -501,6 +571,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 }),