@cadraos/sdk 0.3.14-p46.4 → 0.3.15

package/dist/index.cjs

@@ -63,6 +63,14 @@ var CadraError = class extends Error {
   details;
   /** Request ID from server (for debugging) */
   requestId;
+  /**
+   * The server's own `error.code` exactly as sent on the wire (e.g.
+   * `FUNCTION_NOT_PUBLISHED`, `DUPLICATE_REQUEST`, `VARIABLE_TYPE`).
+   * Populated by `parseApiError` for EVERY status. `code` keeps its historic
+   * per-class values (`conflict`, `server_error`, `validation_error`, …) for
+   * compatibility; branch on `serverCode` when you need the precise reason.
+   */
+  serverCode;
   constructor(message, code, status, details, requestId) {
     super(message);
     this.name = "CadraError";
@@ -140,6 +148,12 @@ function parseApiError(status, body, requestId) {
   const message = errorBody?.error?.message ?? "An error occurred";
   const code = errorBody?.error?.code ?? "unknown_error";
   const details = errorBody?.error?.details;
+  const serverCode = typeof errorBody?.error?.code === "string" ? errorBody.error.code : void 0;
+  const error = buildApiError(status, message, code, details, requestId);
+  if (serverCode !== void 0) error.serverCode = serverCode;
+  return error;
+}
+function buildApiError(status, message, code, details, requestId) {
   switch (status) {
     case 400:
     case 422: {
@@ -175,6 +189,42 @@ function parseApiError(status, body, requestId) {
   }
 }
 
+// src/errors/ai-function-errors.ts
+var AiFunctionDuplicateError = class extends ConflictError {
+  /** The existing run's execution id. */
+  executionId;
+  /** The existing run's status (`running`, a terminal status, or `abandoned`). */
+  runStatus;
+  constructor(message, details, requestId) {
+    super(message, details, requestId);
+    this.name = "AiFunctionDuplicateError";
+    this.serverCode = "DUPLICATE_REQUEST";
+    this.executionId = typeof details?.executionId === "string" ? details.executionId : void 0;
+    this.runStatus = typeof details?.status === "string" ? details.status : void 0;
+  }
+};
+var AiFunctionChargedError = class extends CadraError {
+  constructor(source) {
+    super(source.message, source.code, source.status, source.details, source.requestId);
+    this.name = "AiFunctionChargedError";
+    this.serverCode = source.serverCode;
+  }
+};
+var AiFunctionParameterError = class extends ValidationError {
+  functionKey;
+  issues;
+  constructor(functionKey, issues) {
+    super(
+      `Invalid parameters for AI function "${functionKey}": ` + issues.map((i) => `${i.name} (${i.code})`).join(", "),
+      issues.map((i) => ({ field: i.name, message: i.code })),
+      { functionKey, issues }
+    );
+    this.name = "AiFunctionParameterError";
+    this.functionKey = functionKey;
+    this.issues = issues;
+  }
+};
+
 // src/utils/retry.ts
 var DEFAULT_RETRY_CONFIG = {
   maxRetries: 3,
@@ -239,6 +289,10 @@ var HttpClient = class {
   constructor(config) {
     this.config = config;
   }
+  /** The client-wide request timeout (ms) this client was configured with. */
+  get timeoutMs() {
+    return this.config.timeout;
+  }
   /**
    * Get authorization header value
    */
@@ -293,7 +347,8 @@ var HttpClient = class {
         headers["Idempotency-Key"] = options.idempotencyKey;
       }
       const controller = new AbortController();
-      const timeoutId = setTimeout(() => controller.abort(), this.config.timeout);
+      const timeoutMs = options.timeoutMs ?? this.config.timeout;
+      const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
       try {
         const doFetch = this.config.fetch ?? fetch;
         const response = await doFetch(url, {
@@ -329,7 +384,7 @@ var HttpClient = class {
       } catch (error) {
         clearTimeout(timeoutId);
         if (error instanceof Error && error.name === "AbortError") {
-          throw new TimeoutError(`Request timed out after ${this.config.timeout}ms`);
+          throw new TimeoutError(`Request timed out after ${options.timeoutMs ?? this.config.timeout}ms`);
         }
         if (error instanceof TypeError && error.message.includes("fetch")) {
           throw new NetworkError(`Network error: ${error.message}`);
@@ -361,7 +416,8 @@ var HttpClient = class {
       path,
       body,
       idempotencyKey: options?.idempotencyKey,
-      skipRetry: options?.skipRetry
+      skipRetry: options?.skipRetry,
+      timeoutMs: options?.timeoutMs
     });
   }
   /**
@@ -1120,6 +1176,10 @@ var ExecutionStreamControllerImpl = class {
           toolName,
           result: data.result,
           durationMs: data.durationMs ?? 0,
+          // CAD-243: pass the producer's failure verdict through.
+          ...data.isError === true ? { isError: true } : {},
+          ...typeof data.status === "string" ? { status: data.status } : {},
+          ...typeof data.error === "string" ? { error: data.error } : {},
           forwardedFrom: event.data._forwardedFrom,
           // CAD-87 S1-001 EventIdentity → (execId, seq) reducer dedup (S1-003).
           sourceExecutionId: data.sourceExecutionId ?? data.executionId,
@@ -3358,6 +3418,156 @@ var RemoteRunnersAPI = class extends BaseResourceAPI {
   }
 };
 
+// src/resources/ai-functions.ts
+var AI_FUNCTION_RUN_TIMEOUT_MS = 31e4;
+var AI_FUNCTION_DESCRIPTOR_TTL_MS = 6e4;
+function checkAiFunctionParameters(parameters, variables) {
+  const issues = [];
+  const declared = /* @__PURE__ */ new Set();
+  for (const p of parameters) {
+    declared.add(p.name);
+    const has = Object.prototype.hasOwnProperty.call(variables, p.name);
+    const value = has ? variables[p.name] : void 0;
+    if (value === void 0 || value === null) {
+      if (p.required) issues.push({ name: p.name, code: "missing" });
+      continue;
+    }
+    switch (p.type) {
+      case "number":
+        if (typeof value !== "number" || !Number.isFinite(value)) {
+          issues.push({ name: p.name, code: "type" });
+        }
+        break;
+      case "boolean":
+        if (typeof value !== "boolean") issues.push({ name: p.name, code: "type" });
+        break;
+      case "enum":
+        if (typeof value !== "string") issues.push({ name: p.name, code: "type" });
+        else if (p.options && !p.options.includes(value)) {
+          issues.push({ name: p.name, code: "option" });
+        }
+        break;
+      case "string":
+      case "text":
+        if (typeof value !== "string") issues.push({ name: p.name, code: "type" });
+        else if (typeof p.maxLength === "number" && value.length > p.maxLength) {
+          issues.push({ name: p.name, code: "too_long" });
+        }
+        break;
+      case "image":
+        if (typeof value !== "string") issues.push({ name: p.name, code: "type" });
+        break;
+    }
+  }
+  for (const name of Object.keys(variables)) {
+    if (!declared.has(name)) issues.push({ name, code: "unknown" });
+  }
+  return issues;
+}
+var AiFunctionsAPI = class extends BaseResourceAPI {
+  descriptorCache = /* @__PURE__ */ new Map();
+  constructor(http) {
+    super(http, "/api/v1/ai-functions");
+  }
+  /**
+   * List the functions this org can call — the index (D27a). Each entry carries
+   * the live version's typed parameters; never prompt text.
+   */
+  async list() {
+    const data = await this.httpGet("");
+    const functions = Array.isArray(data) ? data : data?.functions ?? [];
+    for (const d of functions) this.cacheDescriptor(d);
+    return functions;
+  }
+  /**
+   * Get one function's descriptor by key (D27a).
+   * `NotFoundError` (`FUNCTION_NOT_FOUND`) / `ConflictError` (`FUNCTION_NOT_PUBLISHED`).
+   */
+  async get(functionKey) {
+    const data = await this.httpGet(
+      `/${encodeURIComponent(functionKey)}`
+    );
+    const descriptor = data && typeof data === "object" && "function" in data && !("functionKey" in data) ? data.function : data;
+    this.cacheDescriptor(descriptor, functionKey);
+    return descriptor;
+  }
+  /**
+   * Read one of this org's own runs (safe projection, §6.5).
+   */
+  async getRun(executionId) {
+    return this.httpGet(`/runs/${encodeURIComponent(executionId)}`);
+  }
+  /** Forget cached descriptors (one key, or all). */
+  clearDescriptorCache(functionKey) {
+    if (functionKey) this.descriptorCache.delete(functionKey);
+    else this.descriptorCache.clear();
+  }
+  async run(refOrKey, parametersOrOptions, shorthandOpts) {
+    let ref;
+    let options;
+    if (typeof refOrKey === "string") {
+      ref = { functionKey: refOrKey };
+      options = { ...shorthandOpts ?? {}, variables: parametersOrOptions };
+    } else {
+      ref = refOrKey;
+      options = parametersOrOptions;
+    }
+    const variables = options.variables ?? {};
+    const functionKey = "functionKey" in ref ? ref.functionKey : void 0;
+    const shouldCheck = functionKey !== void 0 && options.version === void 0 && options.validate !== false;
+    if (shouldCheck) {
+      const descriptor = await this.getCachedDescriptor(functionKey);
+      const issues = checkAiFunctionParameters(descriptor.parameters, variables);
+      if (issues.length > 0) {
+        throw new AiFunctionParameterError(functionKey, issues);
+      }
+    }
+    const body = {
+      ref,
+      variables,
+      version: options.version,
+      idempotencyKey: options.idempotencyKey ?? generateExecutionId(),
+      params: options.params
+    };
+    try {
+      return await this.httpPost("/run", body, {
+        skipRetry: true,
+        timeoutMs: Math.max(AI_FUNCTION_RUN_TIMEOUT_MS, this.http.timeoutMs ?? 0)
+      });
+    } catch (error) {
+      throw this.mapRunError(error, functionKey);
+    }
+  }
+  // ── internals ──────────────────────────────────────────────────────────────
+  cacheDescriptor(descriptor, key) {
+    if (!descriptor || typeof descriptor !== "object") return;
+    const cacheKey = key ?? descriptor.functionKey;
+    if (!cacheKey) return;
+    this.descriptorCache.set(cacheKey, {
+      descriptor,
+      expiresAt: Date.now() + AI_FUNCTION_DESCRIPTOR_TTL_MS
+    });
+  }
+  async getCachedDescriptor(functionKey) {
+    const hit = this.descriptorCache.get(functionKey);
+    if (hit && hit.expiresAt > Date.now()) return hit.descriptor;
+    return this.get(functionKey);
+  }
+  mapRunError(error, functionKey) {
+    if (!(error instanceof CadraError)) return error;
+    if (error.serverCode === "DUPLICATE_REQUEST") {
+      return new AiFunctionDuplicateError(error.message, error.details, error.requestId);
+    }
+    if (error.details?.charged === true) {
+      return new AiFunctionChargedError(error);
+    }
+    if (functionKey && error.serverCode?.startsWith("VARIABLE_")) {
+      this.descriptorCache.delete(functionKey);
+    }
+    return error;
+  }
+};
+
 // src/client.ts
 var DEFAULT_BASE_URL = "https://api.cadraos.com";
 var DEFAULT_TIMEOUT = 3e4;
@@ -3404,6 +3614,10 @@ var CadraClient = class {
    * Remote runner operations (list)
    */
   remoteRunners;
+  /**
+   * AI function operations (list, get, run, getRun) — p93
+   */
+  aiFunctions;
   /**
    * Create a new AI SaaS client
    *
@@ -3493,6 +3707,7 @@ var CadraClient = class {
     this.kanban = new KanbanAPI(this.httpClient, getStreamConfig);
     this.remoteAgents = new RemoteAgentsAPI(this.httpClient, getStreamConfig);
     this.remoteRunners = new RemoteRunnersAPI(this.httpClient);
+    this.aiFunctions = new AiFunctionsAPI(this.httpClient);
   }
   /**
    * Validate client options
@@ -3517,6 +3732,12 @@ var CadraClient = class {
 
 exports.AISaaSClient = CadraClient;
 exports.AISaaSError = CadraError;
+exports.AI_FUNCTION_DESCRIPTOR_TTL_MS = AI_FUNCTION_DESCRIPTOR_TTL_MS;
+exports.AI_FUNCTION_RUN_TIMEOUT_MS = AI_FUNCTION_RUN_TIMEOUT_MS;
+exports.AiFunctionChargedError = AiFunctionChargedError;
+exports.AiFunctionDuplicateError = AiFunctionDuplicateError;
+exports.AiFunctionParameterError = AiFunctionParameterError;
+exports.AiFunctionsAPI = AiFunctionsAPI;
 exports.AuthenticationError = AuthenticationError;
 exports.AuthorizationError = AuthorizationError;
 exports.CadraClient = CadraClient;
@@ -3528,6 +3749,7 @@ exports.RateLimitError = RateLimitError;
 exports.ServerError = ServerError;
 exports.TimeoutError = TimeoutError;
 exports.ValidationError = ValidationError;
+exports.checkAiFunctionParameters = checkAiFunctionParameters;
 exports.collectImagesFromStream = collectImagesFromStream;
 exports.deriveImagesFromToolCalls = deriveImagesFromToolCalls;
 exports.extractImagesFromExecutionOutput = extractImagesFromExecutionOutput;