@eng-ai/sdk 2.5.0 → 2.8.0

package/CHANGELOG.md

@@ -2,6 +2,48 @@
 
 All notable changes to `@eng-ai/sdk` will be documented in this file.
 
+## 2.8.0 - 2026-04-09
+
+### Added
+
+- External Project Knowledge APIs (v2) in SDK:
+  - `getProjectKnowledgeStatus(projectId)`
+  - `listProjectKnowledgeIssues(projectId, { onlyOpen?, limit? })`
+  - `rebuildProjectKnowledge(projectId, { idempotencyKey? })`
+- Enables API-key integrations to monitor and trigger project knowledge rebuilds directly through SDK.
+
+## 2.7.0 - 2026-04-09
+
+### Added
+
+- External Documents APIs (v2) in SDK:
+  - `listDocuments({ projectId?, tags?, tagMode? })`
+  - `getDocument(documentId)`
+  - `uploadDocument({ file, fileName?, contentType?, projectId?, tags? })`
+  - `updateDocumentTags(documentId, tags)`
+  - `deleteDocument(documentId)`
+- Tag-aware query support for external integrations (`tagMode=any|all` + repeated `tags`).
+
+### Changed
+
+- SDK internals now support multipart requests for file uploads with consistent timeout and error handling.
+
+## 2.6.0 - 2026-04-07
+
+### Added
+
+- Vertex AI BYOK fields in settings APIs:
+  - `setAISettings({ vertexProjectId?, vertexLocation?, vertexServiceAccountJson? })`
+- CLI `eng-ai settings ai set` now supports:
+  - `--provider vertex`
+  - `--vertex-project-id`
+  - `--vertex-location`
+  - `--vertex-service-account-json`
+
+### Security
+
+- SDK debug redaction expanded for service-account sensitive keys (`service_account`, `private_key`, `private_key_id`, `client_email`, `client_id`).
+
 ## 2.5.0 - 2026-04-05
 
 ### Added

package/README.md

@@ -81,6 +81,48 @@ const context = await client.getProjectContext(project.id);
 console.log(context.autonomous_tasks_mode);
 ```
 
+Project knowledge (status, lint issues, manual rebuild):
+
+```js
+const knowledgeStatus = await client.getProjectKnowledgeStatus(project.id);
+const knowledgeIssues = await client.listProjectKnowledgeIssues(project.id, {
+  onlyOpen: true,
+  limit: 10
+});
+await client.rebuildProjectKnowledge(project.id, {
+  idempotencyKey: `knowledge-rebuild-${project.id}`
+});
+
+console.log(knowledgeStatus.status, knowledgeIssues.length);
+```
+
+Project documents (tags, filters, upload, update):
+
+```js
+const uploaded = await client.uploadDocument({
+  file: new Blob(["conteudo tecnico"], { type: "text/plain" }),
+  fileName: "escopo.txt",
+  projectId: project.id,
+  tags: ["Marco Estrutural", "Planejamento"]
+});
+
+await client.updateDocumentTags(uploaded.id, ["Marco Estrutural", "Revisado"]);
+
+const docsAny = await client.listDocuments({
+  projectId: project.id,
+  tags: ["Marco Estrutural", "Revisado"],
+  tagMode: "any"
+});
+
+const docsAll = await client.listDocuments({
+  projectId: project.id,
+  tags: ["Marco Estrutural", "Revisado"],
+  tagMode: "all"
+});
+
+console.log(docsAny.length, docsAll.length);
+```
+
 External approval flow (pull):
 
 ```js
@@ -100,14 +142,23 @@ Supported automation plan actions:
 - `rejectAutomationPlan(projectId, planId, note?, { idempotencyKey? })`
 - `applyAutomationPlan(projectId, planId, { idempotencyKey? })`
 
+Supported project knowledge actions:
+
+- `getProjectKnowledgeStatus(projectId)`
+- `listProjectKnowledgeIssues(projectId, { onlyOpen?, limit? })`
+- `rebuildProjectKnowledge(projectId, { idempotencyKey? })`
+
 External user settings (API key owner scope):
 
 ```js
 const ai = await client.getAISettings();
 await client.setAISettings({
-  provider: "google",
-  model: "gemini-3.1-flash-lite-preview",
-  projectModel: "gemini-3.1-flash-lite-preview",
+  provider: "vertex",
+  model: "gemini-2.5-flash",
+  projectModel: "gemini-2.5-flash",
+  vertexProjectId: "my-gcp-project",
+  vertexLocation: "southamerica-east1",
+  vertexServiceAccountJson: process.env.VERTEX_SERVICE_ACCOUNT_JSON,
   preferredTimezone: "America/Sao_Paulo",
 });
 await client.setVoiceLiveEnabled(true);
@@ -137,6 +188,7 @@ ENG_AI_API_KEY=sk_xxx eng-ai plans apply --project-id <id> --plan-id <id>
 ENG_AI_API_KEY=sk_xxx eng-ai plans watch --interval 15 --limit 30
 ENG_AI_API_KEY=sk_xxx eng-ai settings ai get
 ENG_AI_API_KEY=sk_xxx eng-ai settings ai set --provider google --model gemini-3.1-flash-lite-preview --preferred-timezone America/Sao_Paulo
+ENG_AI_API_KEY=sk_xxx eng-ai settings ai set --provider vertex --model gemini-2.5-flash --vertex-project-id my-gcp-project --vertex-location southamerica-east1 --vertex-service-account-json "$VERTEX_SERVICE_ACCOUNT_JSON"
 ENG_AI_API_KEY=sk_xxx eng-ai settings ai voice-live --enabled true
 ENG_AI_API_KEY=sk_xxx eng-ai settings general set --preferred-timezone America/Sao_Paulo
 ENG_AI_API_KEY=sk_xxx eng-ai profile get

package/bin/eng-ai.js

@@ -66,7 +66,7 @@ Usage:
   eng-ai plans apply --project-id <id> --plan-id <id> [--idempotency-key <key>]
   eng-ai plans watch [--interval <seconds>] [--limit <n>]
   eng-ai settings ai get
-  eng-ai settings ai set --provider <openai|anthropic|google> --model <name> [--project-model <name>] [--api-key <key>] [--google-api-key-rag <key>] [--preferred-timezone <IANA_TZ>]
+  eng-ai settings ai set --provider <openai|anthropic|google|vertex> --model <name> [--project-model <name>] [--api-key <key>] [--google-api-key-rag <key>] [--preferred-timezone <IANA_TZ>] [--vertex-project-id <id>] [--vertex-location <region>] [--vertex-service-account-json <json>]
   eng-ai settings ai clear
   eng-ai settings ai voice-live --enabled <true|false>
   eng-ai settings general get
@@ -244,6 +244,9 @@ async function runSettingsCommand(client, subTokens, options) {
         apiKey: options["api-key"],
         googleApiKeyRag: options["google-api-key-rag"],
         preferredTimezone: options["preferred-timezone"],
+        vertexProjectId: options["vertex-project-id"],
+        vertexLocation: options["vertex-location"],
+        vertexServiceAccountJson: options["vertex-service-account-json"],
       });
       console.log("AI settings updated.");
       console.log(JSON.stringify(result, null, 2));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eng-ai/sdk",
-  "version": "2.5.0",
+  "version": "2.8.0",
   "description": "Official JavaScript SDK for ENG-AI External API v2",
   "type": "module",
   "main": "./src/client.js",

package/src/client.js

@@ -1,11 +1,13 @@
 const DEFAULT_BASE_URL = "https://api.eng-ai.com/api/v2";
 const DEFAULT_TIMEOUT_MS = 60000;
-const REDACT_KEY_PATTERN = /api[-_]?key|authorization|token|secret|password|cookie|set-cookie/i;
+const REDACT_KEY_PATTERN =
+  /api[-_]?key|authorization|token|secret|password|cookie|set-cookie|service[-_]?account|private[-_]?key|private[-_]?key[-_]?id|client[-_]?email|client[-_]?id/i;
 const VALID_AUTONOMOUS_TASKS_MODES = new Set([
   "approval_required",
   "approval_delete_only",
   "full_autonomy",
 ]);
+const VALID_DOCUMENT_TAG_MODES = new Set(["any", "all"]);
 
 function isPlainObject(value) {
   return !!value && Object.prototype.toString.call(value) === "[object Object]";
@@ -165,6 +167,28 @@ export class EngAIClient {
     return { ...this.defaultHeaders, ...extra };
   }
 
+  _normalizeTagArray(tags, fieldName = "tags") {
+    if (tags === undefined || tags === null) return [];
+    if (!Array.isArray(tags)) {
+      throw new EngAIError(`${fieldName} must be an array of strings`, {
+        status: 400,
+        code: "validation_error",
+        detail: `${fieldName} must be an array`,
+      });
+    }
+    const normalized = [];
+    const seen = new Set();
+    for (const rawTag of tags) {
+      const tag = String(rawTag || "").trim().replace(/\s+/g, " ");
+      if (!tag) continue;
+      const key = tag.toLowerCase();
+      if (seen.has(key)) continue;
+      seen.add(key);
+      normalized.push(tag);
+    }
+    return normalized;
+  }
+
   async _parseResponseBody(response) {
     const contentType = String(response.headers.get("content-type") || "").toLowerCase();
     if (contentType.includes("application/json") || contentType.includes("+json")) {
@@ -282,6 +306,77 @@ export class EngAIClient {
     }
   }
 
+  async _requestMultipart(pathname, { method = "POST", formData, headers = {} } = {}) {
+    if (!(formData instanceof FormData)) {
+      throw new EngAIError("formData must be a FormData instance", {
+        status: 400,
+        code: "validation_error",
+        detail: "multipart request requires FormData",
+      });
+    }
+
+    const url = this._buildUrl(pathname);
+    const requestHeaders = {
+      ...this.defaultHeaders,
+      ...headers,
+    };
+    delete requestHeaders["Content-Type"];
+
+    this._log("info", "request.start", {
+      method,
+      url,
+      headers: requestHeaders,
+      body: { type: "form-data" },
+      timeout_ms: this.timeoutMs,
+    });
+
+    try {
+      const response = await this._fetchWithTimeout(url, {
+        method,
+        headers: requestHeaders,
+        body: formData,
+      });
+      const parsedBody = await this._parseResponseBody(response);
+      if (!response.ok) {
+        const err = this._buildHttpError(response, parsedBody, method, url);
+        this._log("warn", "request.error", err.toJSON());
+        throw err;
+      }
+      this._log("info", "request.success", {
+        method,
+        url,
+        status: response.status,
+        request_id: extractRequestId(parsedBody),
+      });
+      return parsedBody;
+    } catch (error) {
+      if (error instanceof EngAIError) throw error;
+      if (error?.name === "AbortError") {
+        const timeoutErr = new EngAIError(
+          `ENG-AI request timeout after ${this.timeoutMs}ms`,
+          { status: 408, code: "request_timeout", method, url, detail: "Request timeout" },
+          error
+        );
+        this._log("warn", "request.timeout", timeoutErr.toJSON());
+        throw timeoutErr;
+      }
+
+      const networkErr = new EngAIError(
+        "ENG-AI network error",
+        {
+          status: 0,
+          code: "network_error",
+          detail: error?.message || "Unknown network error",
+          method,
+          url,
+        },
+        error
+      );
+      this._log("warn", "request.network_error", networkErr.toJSON());
+      throw networkErr;
+    }
+  }
+
   _requireNonEmptyString(value, fieldName) {
     const normalized = String(value || "").trim();
     if (!normalized) {
@@ -378,6 +473,117 @@ export class EngAIClient {
     });
   }
 
+  async listDocuments(options = {}) {
+    const query = new URLSearchParams();
+    if (options.projectId ?? options.project_id) {
+      query.set("project_id", String(options.projectId ?? options.project_id));
+    }
+
+    const tagMode = options.tagMode ?? options.tag_mode;
+    if (tagMode !== undefined && tagMode !== null) {
+      const normalizedTagMode = String(tagMode).trim().toLowerCase();
+      if (!VALID_DOCUMENT_TAG_MODES.has(normalizedTagMode)) {
+        throw new EngAIError("invalid tagMode for listDocuments", {
+          status: 400,
+          code: "validation_error",
+          detail: "tagMode must be one of: any, all",
+        });
+      }
+      query.set("tag_mode", normalizedTagMode);
+    }
+
+    const normalizedTags = this._normalizeTagArray(options.tags, "tags");
+    for (const tag of normalizedTags) {
+      query.append("tags", tag);
+    }
+
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return await this._request(`/documents/${suffix}`, {
+      method: "GET",
+    });
+  }
+
+  async getDocument(documentId) {
+    const normalizedDocumentId = this._requireNonEmptyString(documentId, "documentId");
+    return await this._request(`/documents/${encodeURIComponent(normalizedDocumentId)}`, {
+      method: "GET",
+    });
+  }
+
+  async uploadDocument(payload = {}) {
+    const file = payload.file ?? payload.content;
+    if (file === undefined || file === null) {
+      throw new EngAIError("file is required for uploadDocument", {
+        status: 400,
+        code: "validation_error",
+        detail: "payload.file must be provided",
+      });
+    }
+
+    const formData = new FormData();
+    const filename = String(payload.fileName ?? payload.filename ?? "document.bin");
+    const contentType = payload.contentType ?? payload.content_type;
+    const normalizedProjectId = payload.projectId ?? payload.project_id;
+    const normalizedTags = this._normalizeTagArray(payload.tags, "tags");
+
+    if (
+      file instanceof Blob ||
+      (typeof File !== "undefined" && file instanceof File)
+    ) {
+      formData.append("file", file, filename);
+    } else if (file instanceof ArrayBuffer) {
+      formData.append(
+        "file",
+        new Blob([file], {
+          type: contentType ? String(contentType) : "application/octet-stream",
+        }),
+        filename
+      );
+    } else if (ArrayBuffer.isView(file)) {
+      formData.append(
+        "file",
+        new Blob([file], {
+          type: contentType ? String(contentType) : "application/octet-stream",
+        }),
+        filename
+      );
+    } else {
+      throw new EngAIError("unsupported file type for uploadDocument", {
+        status: 400,
+        code: "validation_error",
+        detail: "file must be Blob, File, ArrayBuffer, Buffer, or Uint8Array",
+      });
+    }
+
+    if (normalizedProjectId) {
+      formData.append("project_id", String(normalizedProjectId));
+    }
+    if (normalizedTags.length > 0) {
+      formData.append("tags", JSON.stringify(normalizedTags));
+    }
+
+    return await this._requestMultipart("/documents/upload", {
+      method: "POST",
+      formData,
+    });
+  }
+
+  async updateDocumentTags(documentId, tags = []) {
+    const normalizedDocumentId = this._requireNonEmptyString(documentId, "documentId");
+    const normalizedTags = this._normalizeTagArray(tags, "tags");
+    return await this._request(`/documents/${encodeURIComponent(normalizedDocumentId)}/tags`, {
+      method: "PATCH",
+      body: { tags: normalizedTags },
+    });
+  }
+
+  async deleteDocument(documentId) {
+    const normalizedDocumentId = this._requireNonEmptyString(documentId, "documentId");
+    return await this._request(`/documents/${encodeURIComponent(normalizedDocumentId)}`, {
+      method: "DELETE",
+    });
+  }
+
   async getAISettings() {
     return await this._request("/settings/llm", {
       method: "GET",
@@ -393,6 +599,10 @@ export class EngAIClient {
       project_model: payload?.projectModel ?? payload?.project_model,
       api_key: payload?.apiKey ?? payload?.api_key,
       google_api_key_rag: payload?.googleApiKeyRag ?? payload?.google_api_key_rag,
+      vertex_project_id: payload?.vertexProjectId ?? payload?.vertex_project_id,
+      vertex_location: payload?.vertexLocation ?? payload?.vertex_location,
+      vertex_service_account_json:
+        payload?.vertexServiceAccountJson ?? payload?.vertex_service_account_json,
       preferred_timezone: payload?.preferredTimezone ?? payload?.preferred_timezone,
     };
 
@@ -468,6 +678,51 @@ export class EngAIClient {
     });
   }
 
+  async getProjectKnowledgeStatus(projectId) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/knowledge/status`,
+      {
+        method: "GET",
+      }
+    );
+  }
+
+  async listProjectKnowledgeIssues(projectId, options = {}) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    const query = new URLSearchParams();
+    if (options.onlyOpen !== undefined) {
+      query.set("only_open", String(!!options.onlyOpen));
+    }
+    if (options.limit !== undefined && options.limit !== null) {
+      query.set("limit", String(options.limit));
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/knowledge/issues${suffix}`,
+      {
+        method: "GET",
+      }
+    );
+  }
+
+  async rebuildProjectKnowledge(projectId, options = {}) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    const headers = {};
+    const idempotencyKey = options?.idempotencyKey ?? options?.idempotency_key;
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/knowledge/rebuild`,
+      {
+        method: "POST",
+        headers,
+        body: {},
+      }
+    );
+  }
+
   async setProjectAutonomyMode(projectId, mode, options = {}) {
     const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
     const normalizedMode = String(mode || "").trim().toLowerCase();