@eng-ai/sdk 2.1.0 → 2.3.0

package/CHANGELOG.md

@@ -2,6 +2,49 @@
 
 All notable changes to `@eng-ai/sdk` will be documented in this file.
 
+## 2.3.0 - 2026-04-05
+
+### Added
+
+- External project autonomy support:
+  - `setProjectAutonomyMode(projectId, mode, { idempotencyKey? })`
+  - `getProjectContext(projectId)`
+- External automation plan approval flow support:
+  - `listActionableAutomationPlans(limit?)`
+  - `listProjectAutomationPlans(projectId, { status? })`
+  - `approveAutomationPlan(projectId, planId, note?, { idempotencyKey? })`
+  - `rejectAutomationPlan(projectId, planId, note?, { idempotencyKey? })`
+  - `applyAutomationPlan(projectId, planId, { idempotencyKey? })`
+- Official package CLI (`eng-ai`) with commands:
+  - `projects autonomy set`
+  - `plans actionable list`
+  - `plans approve|reject|apply`
+  - `plans watch --interval`
+
+## 2.2.0 - 2026-04-05
+
+### Added
+
+- New project management methods in JS SDK:
+  - `createProject(payload)` -> `POST /api/v2/projects/`
+  - `listProjects({ limit, offset })` -> `GET /api/v2/projects/`
+- Enables external CLI/project onboarding flow with API key only.
+- Structured error class `EngAIError` with metadata:
+  - `status`, `code`, `detail`, `requestId`, `retryAfter`, `idempotencyKey`, `method`, `url`
+- Optional client diagnostics with secure redaction:
+  - constructor options: `{ debug, logger, timeoutMs }`
+  - debug logs redact sensitive keys (`api_key`, `authorization`, `token`, `secret`, `password`, `cookie`)
+
+### Changed
+
+- HTTP handling hardened across all SDK calls:
+  - safe JSON/text response parsing
+  - timeout control with `AbortController`
+  - normalized HTTP/network/timeout errors via `EngAIError`
+- Added client-side validation for required inputs:
+  - `invokeAgent`: requires non-empty `message`
+  - `createProject`: requires non-empty `name`
+
 ## 2.1.0 - 2026-04-05
 
 ### Added

package/README.md

@@ -11,23 +11,103 @@ npm install @eng-ai/sdk
 ## Usage
 
 ```js
-import { EngAIClient } from "@eng-ai/sdk";
+import { EngAIClient, EngAIError } from "@eng-ai/sdk";
 
-const client = new EngAIClient(process.env.ENG_AI_API_KEY, "https://your-domain/api/v2");
-
-const response = await client.invokeAgent({
-  message: "Explique o conceito de talude"
-});
-
-// Optional explicit specialist
-const responseWithAgent = await client.invokeAgent("general", {
+const client = new EngAIClient(
+  process.env.ENG_AI_API_KEY,
+  "https://your-domain/api/v2",
+  {
+    debug: false, // set true only in trusted environments
+    timeoutMs: 60000
+  }
+);
+const agentMode = (process.env.ENG_AI_AGENT_MODE || "autonomous").toLowerCase();
+const specialistAgentId = process.env.ENG_AI_AGENT_ID || "general";
+const payload = {
   message: "Explique o conceito de talude",
   normativeMode: true,
   normId: "auto"
+};
+
+const response =
+  agentMode === "specialist"
+    ? await client.invokeAgent(specialistAgentId, payload)
+    : await client.invokeAgent(payload);
+
+console.log(response.result.content);
+console.log(response.normative?.citations ?? []);
+
+// Recommended error handling
+try {
+  await client.invokeAgent(payload);
+} catch (error) {
+  if (error instanceof EngAIError) {
+    console.error("ENG-AI request failed", {
+      status: error.status,
+      code: error.code,
+      detail: error.detail,
+      requestId: error.requestId,
+      retryAfter: error.retryAfter
+    });
+  } else {
+    console.error("Unexpected error", error);
+  }
+}
+```
+
+Agent mode options:
+
+- `ENG_AI_AGENT_MODE=autonomous`: omite `agent_id` e deixa o Core Orchestrator escolher.
+- `ENG_AI_AGENT_MODE=specialist`: fixa `agent_id` via `ENG_AI_AGENT_ID` (ex.: `general`, `contract_manager` ou alias `project_manager`).
+
+Project creation (API key only):
+
+```js
+const project = await client.createProject({
+  name: "Projeto Piloto",
+  description: "Projeto criado via SDK CLI",
+  projectLocation: "São Paulo - SP"
 });
 
-console.log(responseWithAgent.result.content);
-console.log(responseWithAgent.normative?.citations ?? []);
+const projects = await client.listProjects({ limit: 10, offset: 0 });
+console.log(project.id, projects.length);
+```
+
+Task autonomy mode by project:
+
+```js
+await client.setProjectAutonomyMode(project.id, "approval_required");
+const context = await client.getProjectContext(project.id);
+console.log(context.autonomous_tasks_mode);
+```
+
+External approval flow (pull):
+
+```js
+const actionable = await client.listActionableAutomationPlans(30);
+const pending = actionable.find((plan) => plan.status === "pending_approval");
+if (pending) {
+  await client.approveAutomationPlan(pending.project_id, pending.id, "Approved by integration bot");
+  await client.applyAutomationPlan(pending.project_id, pending.id);
+}
+```
+
+Supported automation plan actions:
+
+- `listActionableAutomationPlans(limit?)`
+- `listProjectAutomationPlans(projectId, { status? })`
+- `approveAutomationPlan(projectId, planId, note?, { idempotencyKey? })`
+- `rejectAutomationPlan(projectId, planId, note?, { idempotencyKey? })`
+- `applyAutomationPlan(projectId, planId, { idempotencyKey? })`
+
+CLI (`eng-ai`) included in package:
+
+```bash
+ENG_AI_API_KEY=sk_xxx eng-ai projects autonomy set --project-id <id> --mode approval_required
+ENG_AI_API_KEY=sk_xxx eng-ai plans actionable list --limit 30
+ENG_AI_API_KEY=sk_xxx eng-ai plans approve --project-id <id> --plan-id <id> --note "Approved"
+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
 ```
 
 Default base URL: `https://api.eng-ai.com/api/v2`.
@@ -37,6 +117,7 @@ Default base URL: `https://api.eng-ai.com/api/v2`.
 - Use your ENG-AI API key only in trusted server environments.
 - Do not ship secrets in frontend bundles.
 - Keep idempotency enabled for mutation-heavy integrations.
+- Keep `debug` disabled in production logs unless strictly needed.
 
 ## License
 

package/bin/eng-ai.js

@@ -0,0 +1,219 @@
+#!/usr/bin/env node
+
+import { EngAIClient, EngAIError } from "../src/client.js";
+
+function parseArgs(argv) {
+  const tokens = [];
+  const options = {};
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const item = String(argv[i] || "");
+    if (!item.startsWith("--")) {
+      tokens.push(item);
+      continue;
+    }
+
+    const key = item.slice(2);
+    const next = argv[i + 1];
+    if (next !== undefined && !String(next).startsWith("--")) {
+      options[key] = next;
+      i += 1;
+    } else {
+      options[key] = "true";
+    }
+  }
+
+  return { tokens, options };
+}
+
+function envOrDefault(name, fallback = undefined) {
+  const value = process.env[name];
+  if (value === undefined || value === null || String(value).trim() === "") {
+    return fallback;
+  }
+  return String(value).trim();
+}
+
+function toPositiveInt(value, fallback) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return fallback;
+  return Math.floor(parsed);
+}
+
+function maskId(value) {
+  const text = String(value || "");
+  if (text.length <= 8) return text;
+  return `${text.slice(0, 4)}...${text.slice(-4)}`;
+}
+
+function printHelp() {
+  console.log(`
+ENG-AI SDK CLI
+
+Usage:
+  eng-ai projects autonomy set --project-id <id> --mode <approval_required|approval_delete_only|full_autonomy> [--idempotency-key <key>]
+  eng-ai plans actionable list [--limit <n>]
+  eng-ai plans approve --project-id <id> --plan-id <id> [--note <text>] [--idempotency-key <key>]
+  eng-ai plans reject --project-id <id> --plan-id <id> [--note <text>] [--idempotency-key <key>]
+  eng-ai plans apply --project-id <id> --plan-id <id> [--idempotency-key <key>]
+  eng-ai plans watch [--interval <seconds>] [--limit <n>]
+
+Environment:
+  ENG_AI_API_KEY   (required)
+  ENG_AI_BASE_URL  (optional, default: https://api.eng-ai.com/api/v2)
+`);
+}
+
+function buildClient() {
+  const apiKey = envOrDefault("ENG_AI_API_KEY");
+  if (!apiKey) {
+    throw new Error("ENG_AI_API_KEY is required");
+  }
+  const baseUrl = envOrDefault("ENG_AI_BASE_URL", "https://api.eng-ai.com/api/v2");
+  return new EngAIClient(apiKey, baseUrl);
+}
+
+function printError(error) {
+  if (error instanceof EngAIError) {
+    const payload = {
+      status: error.status,
+      code: error.code,
+      detail: error.detail,
+      requestId: error.requestId,
+      retryAfter: error.retryAfter,
+      idempotencyKey: error.idempotencyKey ? maskId(error.idempotencyKey) : null,
+    };
+    console.error("ENG-AI request failed");
+    console.error(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.error(error?.message || String(error));
+}
+
+async function runProjectsCommand(client, subTokens, options) {
+  if (subTokens[0] !== "autonomy" || subTokens[1] !== "set") {
+    throw new Error("Unsupported projects command. Use: projects autonomy set");
+  }
+
+  const projectId = options["project-id"];
+  const mode = options.mode;
+  const idempotencyKey = options["idempotency-key"];
+  if (!projectId || !mode) {
+    throw new Error("Missing required options: --project-id and --mode");
+  }
+
+  const context = await client.setProjectAutonomyMode(projectId, mode, {
+    idempotencyKey,
+  });
+
+  console.log("Project autonomy mode updated.");
+  console.log(
+    JSON.stringify(
+      {
+        project_id: context.project_id,
+        autonomous_tasks_mode: context.autonomous_tasks_mode,
+        autonomous_tasks_enabled: context.autonomous_tasks_enabled,
+      },
+      null,
+      2
+    )
+  );
+}
+
+function printPlansSummary(plans) {
+  const rows = Array.isArray(plans) ? plans : [];
+  const formatted = rows.map((plan) => ({
+    plan_id: plan.id,
+    project_id: plan.project_id,
+    project_name: plan.project_name || null,
+    status: plan.status,
+    risk_level: plan.risk_level,
+    created_at: plan.created_at,
+  }));
+  console.log(JSON.stringify(formatted, null, 2));
+}
+
+async function runPlansCommand(client, subTokens, options) {
+  const action = subTokens[0];
+
+  if (action === "actionable" && subTokens[1] === "list") {
+    const limit = toPositiveInt(options.limit, 30);
+    const plans = await client.listActionableAutomationPlans(limit);
+    printPlansSummary(plans);
+    return;
+  }
+
+  if (action === "watch") {
+    const intervalSeconds = toPositiveInt(options.interval, 15);
+    const limit = toPositiveInt(options.limit, 30);
+    console.log(
+      `Watching actionable plans every ${intervalSeconds}s (limit=${limit}). Press Ctrl+C to stop.`
+    );
+    while (true) {
+      const plans = await client.listActionableAutomationPlans(limit);
+      const pending = (plans || []).filter((item) => item?.status === "pending_approval");
+      const stamp = new Date().toISOString();
+      console.log(`\n[${stamp}] actionable=${(plans || []).length} pending=${pending.length}`);
+      if (pending.length > 0) {
+        printPlansSummary(pending);
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalSeconds * 1000));
+    }
+  }
+
+  if (!["approve", "reject", "apply"].includes(action)) {
+    throw new Error("Unsupported plans command. Use actionable list|watch|approve|reject|apply");
+  }
+
+  const projectId = options["project-id"];
+  const planId = options["plan-id"];
+  const note = options.note;
+  const idempotencyKey = options["idempotency-key"];
+  if (!projectId || !planId) {
+    throw new Error("Missing required options: --project-id and --plan-id");
+  }
+
+  let result;
+  if (action === "approve") {
+    result = await client.approveAutomationPlan(projectId, planId, note, {
+      idempotencyKey,
+    });
+  } else if (action === "reject") {
+    result = await client.rejectAutomationPlan(projectId, planId, note, {
+      idempotencyKey,
+    });
+  } else {
+    result = await client.applyAutomationPlan(projectId, planId, {
+      idempotencyKey,
+    });
+  }
+
+  console.log(`Plan ${action} completed.`);
+  console.log(JSON.stringify(result, null, 2));
+}
+
+async function main() {
+  const { tokens, options } = parseArgs(process.argv.slice(2));
+  const command = tokens[0];
+  if (!command || command === "help" || command === "--help") {
+    printHelp();
+    return;
+  }
+
+  const client = buildClient();
+  if (command === "projects") {
+    await runProjectsCommand(client, tokens.slice(1), options);
+    return;
+  }
+  if (command === "plans") {
+    await runPlansCommand(client, tokens.slice(1), options);
+    return;
+  }
+
+  throw new Error(`Unknown command: ${command}`);
+}
+
+main().catch((error) => {
+  printError(error);
+  process.exit(1);
+});

package/package.json

@@ -1,13 +1,17 @@
 {
   "name": "@eng-ai/sdk",
-  "version": "2.1.0",
+  "version": "2.3.0",
   "description": "Official JavaScript SDK for ENG-AI External API v2",
   "type": "module",
   "main": "./src/client.js",
+  "bin": {
+    "eng-ai": "./bin/eng-ai.js"
+  },
   "exports": {
     ".": "./src/client.js"
   },
   "files": [
+    "bin",
     "src",
     "README.md",
     "CHANGELOG.md",

package/src/client.js

@@ -1,13 +1,299 @@
+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 VALID_AUTONOMOUS_TASKS_MODES = new Set([
+  "approval_required",
+  "approval_delete_only",
+  "full_autonomy",
+]);
+
+function isPlainObject(value) {
+  return !!value && Object.prototype.toString.call(value) === "[object Object]";
+}
+
+function truncateString(value, max = 300) {
+  const text = String(value);
+  if (text.length <= max) return text;
+  return `${text.slice(0, max)}...(${text.length} chars)`;
+}
+
+function sanitizeForLogs(value, parentKey = "") {
+  if (value === null || value === undefined) return value;
+
+  if (REDACT_KEY_PATTERN.test(parentKey)) {
+    return "[REDACTED]";
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => sanitizeForLogs(item, parentKey));
+  }
+
+  if (isPlainObject(value)) {
+    const output = {};
+    for (const [key, nested] of Object.entries(value)) {
+      output[key] = sanitizeForLogs(nested, key);
+    }
+    return output;
+  }
+
+  if (typeof value === "string") {
+    return truncateString(value);
+  }
+
+  return value;
+}
+
+function describeBody(value) {
+  if (value === null || value === undefined) return null;
+  if (typeof value === "string") return { type: "string", length: value.length };
+  if (Array.isArray(value)) return { type: "array", length: value.length };
+  if (isPlainObject(value)) return { type: "object", keys: Object.keys(value) };
+  return { type: typeof value };
+}
+
+function normalizeErrorDetail(parsedBody, fallback = null) {
+  if (isPlainObject(parsedBody)) {
+    if (typeof parsedBody.detail === "string" && parsedBody.detail.trim()) {
+      return parsedBody.detail.trim();
+    }
+    if (
+      isPlainObject(parsedBody.error) &&
+      typeof parsedBody.error.message === "string" &&
+      parsedBody.error.message.trim()
+    ) {
+      return parsedBody.error.message.trim();
+    }
+    if (typeof parsedBody.message === "string" && parsedBody.message.trim()) {
+      return parsedBody.message.trim();
+    }
+  }
+  if (typeof parsedBody === "string" && parsedBody.trim()) return parsedBody.trim();
+  return fallback;
+}
+
+function extractErrorCode(parsedBody) {
+  if (isPlainObject(parsedBody)) {
+    if (isPlainObject(parsedBody.error) && parsedBody.error.code !== undefined) {
+      return parsedBody.error.code;
+    }
+    if (parsedBody.code !== undefined) return parsedBody.code;
+  }
+  return null;
+}
+
+function extractRequestId(parsedBody) {
+  if (isPlainObject(parsedBody) && isPlainObject(parsedBody.request)) {
+    return parsedBody.request.request_id || null;
+  }
+  return null;
+}
+
+export class EngAIError extends Error {
+  constructor(message, metadata = {}, cause = undefined) {
+    super(message);
+    this.name = "EngAIError";
+    this.status = metadata.status ?? null;
+    this.code = metadata.code ?? null;
+    this.detail = metadata.detail ?? null;
+    this.requestId = metadata.requestId ?? null;
+    this.retryAfter = metadata.retryAfter ?? null;
+    this.idempotencyKey = metadata.idempotencyKey ?? null;
+    this.method = metadata.method ?? null;
+    this.url = metadata.url ?? null;
+
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      code: this.code,
+      detail: this.detail,
+      requestId: this.requestId,
+      retryAfter: this.retryAfter,
+      idempotencyKey: this.idempotencyKey,
+      method: this.method,
+      url: this.url,
+    };
+  }
+}
+
 export class EngAIClient {
-  constructor(apiKey, baseUrl = "https://api.eng-ai.com/api/v2") {
-    this.apiKey = apiKey;
-    this.baseUrl = String(baseUrl || "").replace(/\/+$/, "");
-    this.headers = {
+  constructor(apiKey, baseUrl = DEFAULT_BASE_URL, options = {}) {
+    if (!String(apiKey || "").trim()) {
+      throw new TypeError("ENG-AI API key is required");
+    }
+
+    if (isPlainObject(baseUrl)) {
+      options = baseUrl;
+      baseUrl = DEFAULT_BASE_URL;
+    }
+
+    this.apiKey = String(apiKey).trim();
+    this.baseUrl = String(baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.debug = !!options?.debug;
+    this.timeoutMs = Math.max(1000, Number(options?.timeoutMs || DEFAULT_TIMEOUT_MS));
+    this.logger = options?.logger || console;
+    this.defaultHeaders = {
       "X-API-Key": this.apiKey,
       "Content-Type": "application/json",
     };
   }
 
+  _log(level, event, data = {}) {
+    if (!this.debug) return;
+    const sink =
+      this.logger && typeof this.logger[level] === "function"
+        ? this.logger[level].bind(this.logger)
+        : this.logger && typeof this.logger.log === "function"
+          ? this.logger.log.bind(this.logger)
+          : null;
+    if (!sink) return;
+    sink(`[eng-ai-sdk] ${event}`, sanitizeForLogs(data));
+  }
+
+  _buildUrl(pathname) {
+    const path = pathname.startsWith("/") ? pathname : `/${pathname}`;
+    return `${this.baseUrl}${path}`;
+  }
+
+  _buildHeaders(extra = {}) {
+    return { ...this.defaultHeaders, ...extra };
+  }
+
+  async _parseResponseBody(response) {
+    const contentType = String(response.headers.get("content-type") || "").toLowerCase();
+    if (contentType.includes("application/json") || contentType.includes("+json")) {
+      try {
+        return await response.json();
+      } catch {
+        return null;
+      }
+    }
+
+    const text = await response.text();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+
+  async _fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await fetch(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+
+  _buildHttpError(response, parsedBody, method, url) {
+    const status = Number(response.status || 0);
+    const detail = normalizeErrorDetail(parsedBody, response.statusText || "Request failed");
+    const code = extractErrorCode(parsedBody);
+    const requestId = extractRequestId(parsedBody);
+    const retryAfter = response.headers.get("Retry-After");
+    const idempotencyKey = response.headers.get("Idempotency-Key");
+    const message = `ENG-AI request failed (${status})${detail ? `: ${detail}` : ""}`;
+    return new EngAIError(
+      message,
+      {
+        status,
+        code,
+        detail,
+        requestId,
+        retryAfter,
+        idempotencyKey,
+        method,
+        url,
+      }
+    );
+  }
+
+  async _request(pathname, { method = "GET", body = undefined, headers = {} } = {}) {
+    const url = this._buildUrl(pathname);
+    const requestHeaders = this._buildHeaders(headers);
+    const hasBody = body !== undefined;
+
+    this._log("info", "request.start", {
+      method,
+      url,
+      headers: requestHeaders,
+      body: describeBody(body),
+      timeout_ms: this.timeoutMs,
+    });
+
+    try {
+      const response = await this._fetchWithTimeout(url, {
+        method,
+        headers: requestHeaders,
+        body: hasBody ? JSON.stringify(body) : undefined,
+      });
+
+      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) {
+      throw new EngAIError(`${fieldName} is required`, {
+        status: 400,
+        code: "validation_error",
+        detail: `${fieldName} must be a non-empty string`,
+      });
+    }
+    return normalized;
+  }
+
   async invokeAgent(agentIdOrPayload, maybePayload) {
     const implicitAutonomous = arguments.length === 1;
     const agentId = implicitAutonomous ? null : agentIdOrPayload;
@@ -29,7 +315,15 @@ export class EngAIClient {
             norm_id: payload?.normId ?? payload?.norm_id,
           };
 
-    const headers = { ...this.headers };
+    if (!String(body?.message || "").trim()) {
+      throw new EngAIError("message is required for invokeAgent", {
+        status: 400,
+        code: "validation_error",
+        detail: "message must be a non-empty string",
+      });
+    }
+
+    const headers = {};
     const idempotencyKey = payload?.idempotencyKey ?? payload?.idempotency_key;
     if (idempotencyKey) {
       headers["Idempotency-Key"] = idempotencyKey;
@@ -37,19 +331,164 @@ export class EngAIClient {
 
     const normalizedAgentId = String(agentId || "").trim();
     const endpoint = normalizedAgentId
-      ? `${this.baseUrl}/sdk/agents/${encodeURIComponent(normalizedAgentId)}/invoke`
-      : `${this.baseUrl}/sdk/invoke`;
+      ? `/sdk/agents/${encodeURIComponent(normalizedAgentId)}/invoke`
+      : "/sdk/invoke";
 
-    const response = await fetch(endpoint, {
+    return await this._request(endpoint, {
       method: "POST",
       headers,
-      body: JSON.stringify(body),
+      body,
     });
+  }
 
-    if (!response.ok) {
-      throw new Error(`Error: ${response.statusText}`);
+  async createProject(payload) {
+    if (!String(payload?.name || "").trim()) {
+      throw new EngAIError("name is required for createProject", {
+        status: 400,
+        code: "validation_error",
+        detail: "name must be a non-empty string",
+      });
     }
 
-    return await response.json();
+    const body = {
+      name: payload?.name,
+      description: payload?.description,
+      work_type: payload?.workType ?? payload?.work_type,
+      contractual_start: payload?.contractualStart ?? payload?.contractual_start,
+      contractual_deadline: payload?.contractualDeadline ?? payload?.contractual_deadline,
+      project_location: payload?.projectLocation ?? payload?.project_location,
+      telegram_chat_id: payload?.telegramChatId ?? payload?.telegram_chat_id,
+      vision_cameras: payload?.visionCameras ?? payload?.vision_cameras,
+    };
+
+    return await this._request("/projects/", {
+      method: "POST",
+      body,
+    });
+  }
+
+  async listProjects(options = {}) {
+    const query = new URLSearchParams();
+    if (options.limit !== undefined) query.set("limit", String(options.limit));
+    if (options.offset !== undefined) query.set("offset", String(options.offset));
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+
+    return await this._request(`/projects/${suffix}`, {
+      method: "GET",
+    });
+  }
+
+  async getProjectContext(projectId) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    return await this._request(`/projects/${encodeURIComponent(normalizedProjectId)}/context`, {
+      method: "GET",
+    });
+  }
+
+  async setProjectAutonomyMode(projectId, mode, options = {}) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    const normalizedMode = String(mode || "").trim().toLowerCase();
+    if (!VALID_AUTONOMOUS_TASKS_MODES.has(normalizedMode)) {
+      throw new EngAIError("invalid mode for setProjectAutonomyMode", {
+        status: 400,
+        code: "validation_error",
+        detail:
+          "mode must be one of: approval_required, approval_delete_only, full_autonomy",
+      });
+    }
+
+    const headers = {};
+    const idempotencyKey = options?.idempotencyKey ?? options?.idempotency_key;
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/autonomous-tasks-mode`,
+      {
+        method: "PUT",
+        headers,
+        body: { mode: normalizedMode },
+      }
+    );
+  }
+
+  async listActionableAutomationPlans(limit = 30) {
+    const query = new URLSearchParams();
+    if (limit !== undefined && limit !== null) {
+      query.set("limit", String(limit));
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return await this._request(`/projects/automation-plans/actionable${suffix}`, {
+      method: "GET",
+    });
+  }
+
+  async listProjectAutomationPlans(projectId, options = {}) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    const query = new URLSearchParams();
+    if (options.status) {
+      query.set("status", String(options.status));
+    }
+    const suffix = query.toString() ? `?${query.toString()}` : "";
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/automation-plans${suffix}`,
+      {
+        method: "GET",
+      }
+    );
+  }
+
+  async approveAutomationPlan(projectId, planId, note = undefined, options = {}) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    const normalizedPlanId = this._requireNonEmptyString(planId, "planId");
+    const headers = {};
+    const idempotencyKey = options?.idempotencyKey ?? options?.idempotency_key;
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/automation-plans/${encodeURIComponent(normalizedPlanId)}/approve`,
+      {
+        method: "POST",
+        headers,
+        body: { note: note ?? undefined },
+      }
+    );
+  }
+
+  async rejectAutomationPlan(projectId, planId, note = undefined, options = {}) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    const normalizedPlanId = this._requireNonEmptyString(planId, "planId");
+    const headers = {};
+    const idempotencyKey = options?.idempotencyKey ?? options?.idempotency_key;
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/automation-plans/${encodeURIComponent(normalizedPlanId)}/reject`,
+      {
+        method: "POST",
+        headers,
+        body: { note: note ?? undefined },
+      }
+    );
+  }
+
+  async applyAutomationPlan(projectId, planId, options = {}) {
+    const normalizedProjectId = this._requireNonEmptyString(projectId, "projectId");
+    const normalizedPlanId = this._requireNonEmptyString(planId, "planId");
+    const headers = {};
+    const idempotencyKey = options?.idempotencyKey ?? options?.idempotency_key;
+    if (idempotencyKey) {
+      headers["Idempotency-Key"] = idempotencyKey;
+    }
+    return await this._request(
+      `/projects/${encodeURIComponent(normalizedProjectId)}/automation-plans/${encodeURIComponent(normalizedPlanId)}/apply`,
+      {
+        method: "POST",
+        headers,
+      }
+    );
   }
 }