@declaw/sdk 1.2.3 → 1.4.0

package/dist/index.js

@@ -33,13 +33,51 @@ var ConnectionConfig = class {
   }
 };
 
+// src/api/idempotency.ts
+var CODE_IDEMPOTENCY_IN_PROGRESS = "idempotency_in_progress";
+var CODE_IDEMPOTENCY_KEY_REUSED = "idempotency_key_reused";
+var CODE_TEMPLATE_NOT_READY = "template_not_ready";
+var MAX_RETRY_AFTER_MS = 6e4;
+function newIdempotencyKey() {
+  const c = globalThis.crypto;
+  if (c?.randomUUID) {
+    return c.randomUUID();
+  }
+  if (c?.getRandomValues) {
+    const b = c.getRandomValues(new Uint8Array(16));
+    b[6] = b[6] & 15 | 64;
+    b[8] = b[8] & 63 | 128;
+    const hex = Array.from(b, (x) => x.toString(16).padStart(2, "0")).join("");
+    return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+  }
+  return "";
+}
+function retryAfterMs(response) {
+  const raw = response.headers.get("Retry-After");
+  if (raw === null) return void 0;
+  const secs = Number(raw);
+  if (!Number.isFinite(secs) || secs < 0) return void 0;
+  return Math.min(secs * 1e3, MAX_RETRY_AFTER_MS);
+}
+
 // src/errors.ts
 var SandboxError = class extends Error {
   sandboxId;
+  /**
+   * Machine-readable error code from the API's `code` field, when present.
+   *
+   * Branch on this, never on `message`. Messages are prose and change; codes are
+   * contract. It matters most where one status means several unrelated things:
+   * a 409 from `POST /sandboxes` is either `idempotency_in_progress` (the
+   * original create is still running — retry the identical request) or
+   * `template_not_ready` (rebuild the template; retrying cannot help).
+   */
+  code;
   constructor(message, opts) {
     super(message);
     this.name = "SandboxError";
     this.sandboxId = opts?.sandboxId;
+    this.code = opts?.code;
   }
 };
 var TimeoutError = class extends SandboxError {
@@ -297,6 +335,15 @@ var ApiClient = class {
           await this.delay(attempt);
           continue;
         }
+        if (response.status === 409 && attempt < this.maxRetries - 1) {
+          const parsed = await this.readErrorBody(response);
+          if (parsed.code === CODE_IDEMPOTENCY_IN_PROGRESS) {
+            const after = retryAfterMs(response);
+            await (after !== void 0 ? new Promise((r) => setTimeout(r, after)) : this.delay(attempt));
+            continue;
+          }
+          throw this.errorFrom(response, parsed);
+        }
         if (!response.ok) {
           throw await this.buildError(response);
         }
@@ -322,20 +369,36 @@ var ApiClient = class {
       `Request failed after ${this.maxRetries} retries: ${lastError?.message ?? "unknown error"}`
     );
   }
-  async buildError(response) {
-    let message;
+  /**
+   * Read an error body ONCE.
+   *
+   * `Response` bodies are single-read streams, so the 409 path cannot inspect
+   * the code and then hand the response to a separate error builder — the
+   * second read yields nothing and the error loses its message. Everything that
+   * needs the body goes through here, and the parsed result is passed around
+   * instead of the response.
+   */
+  async readErrorBody(response) {
     try {
-      const body = await response.json();
+      const body = JSON.parse(await response.text());
       const bodyMsg = body.message ?? body.error ?? response.statusText;
-      message = `HTTP ${response.status}: ${bodyMsg}`;
+      return {
+        message: `HTTP ${response.status}: ${bodyMsg}`,
+        code: typeof body.code === "string" ? body.code : void 0
+      };
     } catch {
-      message = `HTTP ${response.status}: ${response.statusText}`;
+      return { message: `HTTP ${response.status}: ${response.statusText}` };
     }
+  }
+  errorFrom(response, parsed) {
     const ErrorClass = STATUS_ERROR_MAP[response.status];
     if (ErrorClass) {
-      return new ErrorClass(message);
+      return new ErrorClass(parsed.message, { code: parsed.code });
     }
-    return new SandboxError(message);
+    return new SandboxError(parsed.message, { code: parsed.code });
+  }
+  async buildError(response) {
+    return this.errorFrom(response, await this.readErrorBody(response));
   }
   async parseResponseBody(response) {
     const contentLength = response.headers.get("content-length");
@@ -509,7 +572,7 @@ function createInjectionDefenseConfig(opts) {
     enabled: opts?.enabled ?? false,
     sensitivity: opts?.sensitivity ?? "medium" /* Medium */,
     action: opts?.action ?? "log_only" /* LogOnly */,
-    threshold: opts?.threshold ?? 0.8,
+    threshold: opts?.threshold ?? 0.95,
     domains: opts?.domains,
     judge: opts?.judge,
     injectionMode: opts?.injectionMode
@@ -536,7 +599,7 @@ function parseInjectionDefenseConfig(data) {
     enabled: data.enabled ?? false,
     sensitivity: data.sensitivity ?? "medium" /* Medium */,
     action: data.action ?? "log_only" /* LogOnly */,
-    threshold: data.threshold ?? 0.8,
+    threshold: data.threshold ?? 0.95,
     domains: data.domains,
     judge: data.judge ? { enabled: data.judge.enabled ?? false, always: data.judge.always, policy: data.judge.policy } : void 0,
     injectionMode: data.injection_mode ?? data.injectionMode
@@ -914,14 +977,14 @@ function fullInjectionDefensePolicy(opts) {
     injectionDefense: createInjectionDefenseConfig({
       enabled: true,
       action: opts?.action ?? "block",
-      threshold: opts?.threshold ?? 0.8,
+      threshold: opts?.threshold ?? 0.95,
       domains: opts?.domains,
       injectionMode: opts?.mode ?? "balanced",
       judge: { enabled: true, always: opts?.alwaysJudge ?? false, policy: opts?.agentPolicy ?? "" }
     }),
     customPolicy: createCustomPolicyConfig({
       enabled: true,
-      policyRef: "prompt-injection@v2",
+      policyRef: "prompt-injection@v3",
       defaultDeny: false
     })
   });
@@ -962,7 +1025,7 @@ function securityPolicyToJSON(policy) {
     action: injDefConfig.action,
     threshold: injDefConfig.threshold
   };
-  if (injDefConfig.domains !== void 0) {
+  if (injDefConfig.domains !== void 0 && injDefConfig.domains.length > 0) {
     injDef.domains = injDefConfig.domains;
   }
   if (injDefConfig.injectionMode !== void 0) {
@@ -2074,6 +2137,311 @@ function volumeAttachmentToJSON(att) {
   return out;
 }
 
+// src/vault/models.ts
+function parseVaultScope(data) {
+  const scope = {
+    domainRegex: String(data.domain_regex ?? "")
+  };
+  if (data.injection_type !== void 0 && data.injection_type !== null) {
+    scope.injectionType = String(data.injection_type);
+  }
+  if (data.header_name !== void 0 && data.header_name !== null) {
+    scope.headerName = String(data.header_name);
+  }
+  if (data.value_prefix !== void 0 && data.value_prefix !== null) {
+    scope.valuePrefix = String(data.value_prefix);
+  }
+  if (data.basic_username !== void 0 && data.basic_username !== null) {
+    scope.basicUsername = String(data.basic_username);
+  }
+  if (data.extra_headers !== void 0 && data.extra_headers !== null) {
+    scope.extraHeaders = data.extra_headers;
+  }
+  if (data.query_params !== void 0 && data.query_params !== null) {
+    scope.queryParams = data.query_params;
+  }
+  return scope;
+}
+function parseVaultSecret(data) {
+  const secret = {
+    secretId: String(data.secret_id ?? ""),
+    name: String(data.name ?? ""),
+    createdAt: String(data.created_at ?? ""),
+    updatedAt: String(data.updated_at ?? "")
+  };
+  const rawScopes = data.scopes;
+  if (rawScopes && rawScopes.length > 0) {
+    secret.scopes = rawScopes.map(parseVaultScope);
+  }
+  if (data.rotated_at !== void 0 && data.rotated_at !== null) {
+    secret.rotatedAt = String(data.rotated_at);
+  }
+  if (data.rotation_interval_days !== void 0 && data.rotation_interval_days !== null) {
+    secret.rotationIntervalDays = Number(data.rotation_interval_days);
+  }
+  if (data.rotation_due !== void 0 && data.rotation_due !== null) {
+    secret.rotationDue = Boolean(data.rotation_due);
+  }
+  return secret;
+}
+function parseVaultPreset(data) {
+  const rawScopes = data.scopes ?? [];
+  const preset = {
+    key: String(data.key ?? ""),
+    name: String(data.name ?? ""),
+    category: String(data.category ?? ""),
+    keyHint: String(data.key_hint ?? ""),
+    scopes: rawScopes.map(parseVaultScope)
+  };
+  if (data.docs_url !== void 0 && data.docs_url !== null) {
+    preset.docsUrl = String(data.docs_url);
+  }
+  return preset;
+}
+function vaultScopeToJSON(scope) {
+  const out = {
+    domain_regex: scope.domainRegex
+  };
+  if (scope.injectionType !== void 0) {
+    out.injection_type = scope.injectionType;
+  }
+  if (scope.headerName !== void 0) {
+    out.header_name = scope.headerName;
+  }
+  if (scope.valuePrefix !== void 0) {
+    out.value_prefix = scope.valuePrefix;
+  }
+  if (scope.basicUsername !== void 0) {
+    out.basic_username = scope.basicUsername;
+  }
+  if (scope.extraHeaders !== void 0) {
+    out.extra_headers = scope.extraHeaders;
+  }
+  if (scope.queryParams !== void 0) {
+    out.query_params = scope.queryParams;
+  }
+  return out;
+}
+
+// src/vault/vault.ts
+var DEFAULT_TEAM_NAME = "default";
+var DEFAULT_ENV_NAME = "prod";
+var defaultTeamCache = /* @__PURE__ */ new Map();
+function cacheKey(config) {
+  return `${config.apiUrl}\0${config.apiKey}`;
+}
+async function resolveDefaultTeamId(config, create, timeout) {
+  const key = cacheKey(config);
+  const cached = defaultTeamCache.get(key);
+  if (cached !== void 0) return cached;
+  const client = getSharedClient(config);
+  const resp = await client.get("/teams", { timeout });
+  const rows = resp.teams ?? [];
+  let best = null;
+  for (const t of rows) {
+    if (t.name === DEFAULT_TEAM_NAME) {
+      if (best === null || t.created_at < best.created_at) {
+        best = t;
+      }
+    }
+  }
+  if (best !== null) {
+    defaultTeamCache.set(key, best.team_id);
+    return best.team_id;
+  }
+  if (!create) return null;
+  const created = await client.post("/teams", {
+    json: { name: DEFAULT_TEAM_NAME },
+    timeout
+  });
+  defaultTeamCache.set(key, created.team_id);
+  return created.team_id;
+}
+async function ensureDefaultEnv(config, teamId, timeout) {
+  const client = getSharedClient(config);
+  const resp = await client.get(
+    `/teams/${encodeURIComponent(teamId)}/environments`,
+    { timeout }
+  );
+  const rows = resp.environments ?? [];
+  if (rows.some((e) => e.name === DEFAULT_ENV_NAME)) return;
+  try {
+    await client.post(`/teams/${encodeURIComponent(teamId)}/environments`, {
+      json: { name: DEFAULT_ENV_NAME },
+      timeout
+    });
+  } catch {
+    const resp2 = await client.get(
+      `/teams/${encodeURIComponent(teamId)}/environments`,
+      { timeout }
+    );
+    const rows2 = resp2.environments ?? [];
+    if (rows2.some((e) => e.name === DEFAULT_ENV_NAME)) return;
+    throw new Error(`Failed to ensure default environment "${DEFAULT_ENV_NAME}" on team ${teamId}`);
+  }
+}
+async function expandVaultRefs(config, refs, timeout) {
+  if (Object.keys(refs).length === 0) return refs;
+  const needsTeam = Object.values(refs).some((v) => !v.startsWith("vault://"));
+  if (!needsTeam) return refs;
+  const teamId = await resolveDefaultTeamId(config, false, timeout);
+  if (teamId === null) {
+    throw new Error("vault_refs given but no vault secrets exist for this account");
+  }
+  const out = {};
+  for (const [envVar, ref] of Object.entries(refs)) {
+    out[envVar] = ref.startsWith("vault://") ? ref : `vault://${teamId}/${DEFAULT_ENV_NAME}/${ref}`;
+  }
+  return out;
+}
+function buildConfig(opts) {
+  return new ConnectionConfig({
+    apiKey: opts?.apiKey,
+    domain: opts?.domain,
+    apiUrl: opts?.apiUrl,
+    requestTimeout: opts?.requestTimeout
+  });
+}
+var Vault = class _Vault {
+  // -------------------------------------------------------------------------
+  // Secrets
+  // -------------------------------------------------------------------------
+  /**
+   * Store a secret's value (server-side, in OpenBao) plus its injection
+   * scopes, under the auto-provisioned default team + "prod" environment.
+   * Returns metadata only — the value is never echoed.
+   *
+   * POST /teams/{teamId}/vault/secrets
+   */
+  static async createSecret(input, opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, true, opts?.requestTimeout);
+    if (teamId === null) throw new Error("Failed to resolve or create default team");
+    await ensureDefaultEnv(config, teamId, opts?.requestTimeout);
+    const body = {
+      environment: DEFAULT_ENV_NAME,
+      value: input.value
+    };
+    if (input.name) body.name = input.name;
+    if (input.provider) body.provider = input.provider;
+    if (input.scopes && input.scopes.length > 0) {
+      body.scopes = input.scopes.map(vaultScopeToJSON);
+    }
+    if (input.rotationIntervalDays && input.rotationIntervalDays > 0) {
+      body.rotation_interval_days = input.rotationIntervalDays;
+    }
+    const client = getSharedClient(config);
+    const resp = await client.post(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets`,
+      { json: body, timeout: opts?.requestTimeout }
+    );
+    return parseVaultSecret(resp);
+  }
+  /**
+   * List secret metadata for the default team. Returns an empty array if no
+   * default team has been provisioned yet.
+   *
+   * GET /teams/{teamId}/vault/secrets -> {secrets}
+   */
+  static async listSecrets(opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) return [];
+    const client = getSharedClient(config);
+    const resp = await client.get(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets`,
+      { timeout: opts?.requestTimeout }
+    );
+    const rows = resp.secrets ?? [];
+    return rows.map(parseVaultSecret);
+  }
+  /**
+   * Replace a secret's value by name (server-side); scopes are unchanged.
+   *
+   * POST /teams/{teamId}/vault/secrets/{secretId}/rotate {value}
+   */
+  static async rotateSecret(name, value, opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) throw new Error(`vault secret "${name}" not found`);
+    const secretId = await _Vault._resolveSecretId(config, teamId, name, opts?.requestTimeout);
+    const client = getSharedClient(config);
+    await client.post(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets/${encodeURIComponent(secretId)}/rotate`,
+      { json: { value }, timeout: opts?.requestTimeout }
+    );
+  }
+  /**
+   * Delete a secret by name — metadata and stored value.
+   *
+   * DELETE /teams/{teamId}/vault/secrets/{secretId}
+   */
+  static async deleteSecret(name, opts) {
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) throw new Error(`vault secret "${name}" not found`);
+    const secretId = await _Vault._resolveSecretId(config, teamId, name, opts?.requestTimeout);
+    const client = getSharedClient(config);
+    await client.delete(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets/${encodeURIComponent(secretId)}`,
+      { timeout: opts?.requestTimeout }
+    );
+  }
+  /**
+   * Replace a secret's injection scopes by name; the value is unchanged. Use
+   * this to change a secret's destination(s) or injection format in place
+   * instead of delete + recreate. At least one scope is required.
+   *
+   * POST /teams/{teamId}/vault/secrets/{secretId}/scopes
+   */
+  static async updateScopes(name, scopes, opts) {
+    if (!scopes || scopes.length === 0) {
+      throw new Error("at least one scope is required");
+    }
+    const config = buildConfig(opts);
+    const teamId = await resolveDefaultTeamId(config, false, opts?.requestTimeout);
+    if (teamId === null) throw new Error(`vault secret "${name}" not found`);
+    const secretId = await _Vault._resolveSecretId(config, teamId, name, opts?.requestTimeout);
+    const client = getSharedClient(config);
+    await client.post(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets/${encodeURIComponent(secretId)}/scopes`,
+      { json: { scopes: scopes.map(vaultScopeToJSON) }, timeout: opts?.requestTimeout }
+    );
+  }
+  // -------------------------------------------------------------------------
+  // Presets
+  // -------------------------------------------------------------------------
+  /**
+   * List built-in provider preset catalog (templates only, no secret material).
+   *
+   * GET /vault/presets -> {presets}
+   */
+  static async listPresets(opts) {
+    const client = getSharedClient(buildConfig(opts));
+    const resp = await client.get("/vault/presets", {
+      timeout: opts?.requestTimeout
+    });
+    const rows = resp.presets ?? [];
+    return rows.map(parseVaultPreset);
+  }
+  // -------------------------------------------------------------------------
+  // Internal helpers
+  // -------------------------------------------------------------------------
+  /** Maps a secret name to its id within the given team. */
+  static async _resolveSecretId(config, teamId, name, timeout) {
+    const client = getSharedClient(config);
+    const resp = await client.get(
+      `/teams/${encodeURIComponent(teamId)}/vault/secrets`,
+      { timeout }
+    );
+    const rows = resp.secrets ?? [];
+    for (const s of rows) {
+      if (s.name === name) return String(s.secret_id ?? "");
+    }
+    throw new Error(`vault secret "${name}" not found`);
+  }
+};
+
 // src/sandbox/sandbox.ts
 var DEFAULT_TEMPLATE = "base";
 var DEFAULT_TIMEOUT = 300;
@@ -2219,6 +2587,9 @@ var Sandbox = class _Sandbox {
     if (opts?.envs) {
       body.envs = opts.envs;
     }
+    if (opts?.vaultRefs) {
+      body.vault_refs = await expandVaultRefs(config, opts.vaultRefs, opts.requestTimeout);
+    }
     if (opts?.network) {
       body.network = networkOptsToJSON(opts.network);
     } else if (opts?.allowInternetAccess === false) {
@@ -2236,9 +2607,11 @@ var Sandbox = class _Sandbox {
     if (opts?.volumes && opts.volumes.length > 0) {
       body.volumes = opts.volumes.map(volumeAttachmentToJSON);
     }
+    const idempotencyKey = newIdempotencyKey();
     const data = await client.post("/sandboxes", {
       json: body,
-      timeout: opts?.requestTimeout
+      timeout: opts?.requestTimeout,
+      ...idempotencyKey ? { headers: { "Idempotency-Key": idempotencyKey } } : {}
     });
     const sandboxId = data.sandbox_id;
     assertValidId(sandboxId, "sandbox ID (from server)");
@@ -3122,7 +3495,16 @@ function assertValidVolumeId3(id) {
   }
 }
 var Volumes = class {
-  /** Create a volume by streaming a tarball (gzip tar.gz) to the server. */
+  /**
+   * Create a volume named `name`, optionally populated with `data`.
+   *
+   * `POST /volumes` is the canonical create endpoint. With `data` (a gzip tar.gz)
+   * the body is ingested into a new file-granular volume (or a legacy tarball
+   * blob if no file-granular backend is configured). Creating an empty volume
+   * (no `data`, or an empty buffer) requires a file-granular backend.
+   * `empty(name)` / `ingest(name, data)` remain available for explicit,
+   * backend-specific control.
+   */
   static async create(name, data, opts) {
     if (!name) {
       throw new InvalidArgumentError("volume name is required");
@@ -3134,6 +3516,13 @@ var Volumes = class {
       requestTimeout: opts?.requestTimeout
     });
     const client = getSharedClient(config);
+    if (data === void 0 || data.byteLength === 0) {
+      const resp2 = await client.post("/volumes", {
+        params: { name },
+        timeout: opts?.requestTimeout
+      });
+      return parseVolumeInfo(resp2);
+    }
     const body = data instanceof Uint8Array ? data : new Uint8Array(data);
     const resp = await client.post("/volumes", {
       params: { name },
@@ -3403,6 +3792,9 @@ export {
   ApiClient,
   AuthenticationError,
   BuildError,
+  CODE_IDEMPOTENCY_IN_PROGRESS,
+  CODE_IDEMPOTENCY_KEY_REUSED,
+  CODE_TEMPLATE_NOT_READY,
   CommandExitError,
   CommandHandle,
   Commands,
@@ -3437,6 +3829,7 @@ export {
   TemplateError,
   TimeoutError,
   TransformDirection,
+  Vault,
   VolumeFiles,
   VolumeLocks,
   Volumes,
@@ -3488,6 +3881,9 @@ export {
   parseSnapshotInfo,
   parseTemplateBuildStatus,
   parseToxicityConfig,
+  parseVaultPreset,
+  parseVaultScope,
+  parseVaultSecret,
   parseVolumeInfo,
   parseWriteInfo,
   requiresTlsInterception,
@@ -3495,6 +3891,7 @@ export {
   securityPolicyToJSON,
   toxicityConfigToJSON,
   validateNetworkEntry,
+  vaultScopeToJSON,
   volumeAttachmentToJSON
 };
 //# sourceMappingURL=index.js.map