@cavsnode/cavs-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,1139 @@
+var __defProp = Object.defineProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/errors.ts
+var CAVSError = class extends Error {
+  code;
+  status;
+  requestId;
+  retryAfterMs;
+  constructor(message, options = {}) {
+    super(message, options.cause !== void 0 ? { cause: options.cause } : void 0);
+    this.name = new.target.name;
+    this.code = options.code;
+    this.status = options.status;
+    this.requestId = options.requestId;
+    this.retryAfterMs = options.retryAfterMs;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends CAVSError {
+};
+var AuthorizationError = class extends CAVSError {
+};
+var NotFoundError = class extends CAVSError {
+};
+var ConflictError = class extends CAVSError {
+};
+var RateLimitError = class extends CAVSError {
+};
+var QuotaExceededError = class extends CAVSError {
+};
+var ChecksumError = class extends CAVSError {
+};
+var UploadError = class extends CAVSError {
+};
+var DownloadError = class extends CAVSError {
+};
+var TemporaryServiceError = class extends CAVSError {
+};
+function toCAVSError(status, body, extra = {}) {
+  const envelope = body ?? {};
+  const code = envelope.error?.code;
+  const message = envelope.error?.message ?? `CAVS request failed with status ${status}`;
+  const opts = {
+    code,
+    status,
+    requestId: extra.requestId,
+    retryAfterMs: extra.retryAfterMs
+  };
+  switch (status) {
+    case 401:
+      return new AuthenticationError(message, opts);
+    case 403:
+      return new AuthorizationError(message, opts);
+    case 404:
+      return new NotFoundError(message, opts);
+    case 409:
+      return new ConflictError(message, opts);
+    case 402:
+    case 413:
+      return new QuotaExceededError(message, opts);
+    case 429:
+      return new RateLimitError(message, opts);
+    case 426:
+      return new CAVSError(message, opts);
+    default:
+      if (status >= 500) {
+        return new TemporaryServiceError(message, opts);
+      }
+      if (code === "quota_exceeded") {
+        return new QuotaExceededError(message, opts);
+      }
+      return new CAVSError(message, opts);
+  }
+}
+
+// src/auth.ts
+function resolveToken(explicit, env = process.env) {
+  const token = explicit ?? env.CAVS_TOKEN;
+  if (!token || token.trim() === "") {
+    throw new AuthenticationError(
+      "No CAVS token provided. Pass { token } or set the CAVS_TOKEN environment variable."
+    );
+  }
+  return token.trim();
+}
+
+// src/telemetry.ts
+var VERSION = "0.1.0";
+var CLIENT_ID = "javascript-sdk";
+function telemetryHeaders(opts = {}) {
+  const headers = {
+    "User-Agent": `cavs-node/${VERSION}`,
+    "X-CAVS-Client": CLIENT_ID,
+    "X-CAVS-Integration": opts.integration ?? CLIENT_ID,
+    "X-CAVS-Integration-Version": opts.integrationVersion ?? VERSION
+  };
+  if (opts.runId) {
+    headers["X-CAVS-Run-ID"] = opts.runId;
+  }
+  return headers;
+}
+
+// src/http.ts
+var RETRYABLE_STATUS = (status) => status === 429 || status >= 500;
+var HttpClient = class {
+  baseUrl;
+  token;
+  fetchImpl;
+  telemetry;
+  maxRetries;
+  maxRedirects;
+  timeoutMs;
+  retryBaseMs;
+  maxBackoffMs;
+  onDeprecation;
+  sleepImpl;
+  constructor(opts) {
+    this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
+    this.token = opts.token;
+    this.fetchImpl = opts.fetch ?? fetch;
+    this.telemetry = opts.telemetry ?? {};
+    this.maxRetries = opts.maxRetries ?? 4;
+    this.maxRedirects = opts.maxRedirects ?? 5;
+    this.timeoutMs = opts.timeoutMs ?? 3e4;
+    this.retryBaseMs = opts.retryBaseMs ?? 200;
+    this.maxBackoffMs = opts.maxBackoffMs ?? 3e4;
+    this.onDeprecation = opts.onDeprecation ?? ((message) => {
+      console.warn(`[cavs] deprecation: ${message}`);
+    });
+    this.sleepImpl = opts.sleepImpl ?? ((ms) => new Promise((resolve2) => setTimeout(resolve2, ms)));
+  }
+  /** Build the standard header set for a control-plane request. */
+  baseHeaders(extra) {
+    return {
+      Authorization: `Bearer ${this.token}`,
+      Accept: "application/json",
+      ...telemetryHeaders(this.telemetry),
+      ...extra
+    };
+  }
+  buildUrl(path2, query) {
+    const suffix = path2.startsWith("/") ? path2 : `/${path2}`;
+    const full = new URL(this.baseUrl + suffix);
+    if (query) {
+      for (const [key, value] of Object.entries(query)) {
+        if (value !== void 0) {
+          full.searchParams.set(key, String(value));
+        }
+      }
+    }
+    return full.toString();
+  }
+  /** Perform a JSON control-plane request with retries and typed errors. */
+  async requestJson(opts) {
+    const method = opts.method ?? "GET";
+    const url = this.buildUrl(opts.path, opts.query);
+    const headers = this.baseHeaders(opts.headers);
+    let body;
+    if (opts.body !== void 0) {
+      body = JSON.stringify(opts.body);
+      headers["Content-Type"] = "application/json";
+    }
+    if (opts.idempotencyKey) {
+      headers["Idempotency-Key"] = opts.idempotencyKey;
+    }
+    const res = await this.executeWithRetry(url, { method, headers, body }, opts.signal);
+    return this.parseJson(res);
+  }
+  /**
+   * Send a request whose body is a (possibly streamed) factory, retrying with a
+   * fresh body each attempt. Used for presigned PUT uploads. Returns the raw
+   * Response. Presigned URLs must never be logged.
+   */
+  async sendStream(url, opts) {
+    return this.executeWithRetry(
+      url,
+      {
+        method: opts.method,
+        headers: opts.headers ?? {},
+        bodyFactory: opts.bodyFactory,
+        extraInit: opts.init
+      },
+      opts.signal,
+      /* isDataPlane */
+      true
+    );
+  }
+  /** Open a streaming GET (presigned download). Returns the raw Response. */
+  async openStream(url, opts = {}) {
+    return this.executeWithRetry(
+      url,
+      { method: "GET", headers: {} },
+      opts.signal,
+      /* isDataPlane */
+      true
+    );
+  }
+  async executeWithRetry(url, req, externalSignal, isDataPlane = false) {
+    let lastError;
+    for (let attempt = 0; ; attempt++) {
+      const { signal, cleanup, timedOut } = this.armSignal(externalSignal);
+      try {
+        const body = req.bodyFactory ? req.bodyFactory() : req.body;
+        const init = {
+          method: req.method,
+          headers: req.headers,
+          signal,
+          ...req.extraInit
+        };
+        if (body !== void 0) {
+          init.body = body;
+        }
+        const res = await this.fetchWithRedirects(url, init);
+        if (!isDataPlane) {
+          const dep = res.headers.get("x-cavs-deprecation");
+          if (dep) {
+            this.safeDeprecation(dep);
+          }
+        }
+        if (res.ok) {
+          return res;
+        }
+        if (RETRYABLE_STATUS(res.status) && attempt < this.maxRetries) {
+          const wait = this.retryAfterMs(res) ?? this.backoff(attempt);
+          cleanup();
+          await this.sleepImpl(wait);
+          continue;
+        }
+        throw await this.toError(res);
+      } catch (err) {
+        if (externalSignal?.aborted) {
+          cleanup();
+          throw externalSignal.reason instanceof Error ? externalSignal.reason : new CAVSError("Request cancelled", { cause: externalSignal.reason });
+        }
+        if (err instanceof CAVSError) {
+          cleanup();
+          throw err;
+        }
+        lastError = err;
+        if (attempt < this.maxRetries) {
+          cleanup();
+          await this.sleepImpl(this.backoff(attempt));
+          continue;
+        }
+        cleanup();
+        const reason = timedOut() ? "request timed out" : "network error";
+        throw new TemporaryServiceError(`CAVS ${reason} after ${attempt + 1} attempt(s)`, {
+          cause: err
+        });
+      } finally {
+        cleanup();
+      }
+    }
+    throw new TemporaryServiceError("CAVS request failed", { cause: lastError });
+  }
+  /** Follow redirects manually, bounded by {@link maxRedirects}. */
+  async fetchWithRedirects(url, init) {
+    let current = url;
+    for (let i = 0; i <= this.maxRedirects; i++) {
+      const res = await this.fetchImpl(current, { ...init, redirect: "manual" });
+      const location = res.headers.get("location");
+      if (res.status >= 300 && res.status < 400 && location) {
+        if (i === this.maxRedirects) {
+          throw new TemporaryServiceError(
+            `Too many redirects (>${this.maxRedirects})`,
+            { status: res.status }
+          );
+        }
+        current = new URL(location, current).toString();
+        continue;
+      }
+      return res;
+    }
+    throw new TemporaryServiceError("Redirect handling failed");
+  }
+  armSignal(external) {
+    const controller = new AbortController();
+    let didTimeout = false;
+    const timer = setTimeout(() => {
+      didTimeout = true;
+      controller.abort(new Error("timeout"));
+    }, this.timeoutMs);
+    const onExternal = () => controller.abort(external?.reason);
+    if (external) {
+      if (external.aborted) {
+        controller.abort(external.reason);
+      } else {
+        external.addEventListener("abort", onExternal);
+      }
+    }
+    let done = false;
+    const cleanup = () => {
+      if (done) return;
+      done = true;
+      clearTimeout(timer);
+      external?.removeEventListener("abort", onExternal);
+    };
+    return { signal: controller.signal, cleanup, timedOut: () => didTimeout };
+  }
+  backoff(attempt) {
+    const base = this.retryBaseMs * Math.pow(2, attempt);
+    const jitter = Math.random() * this.retryBaseMs;
+    return Math.min(base + jitter, this.maxBackoffMs);
+  }
+  retryAfterMs(res) {
+    const header = res.headers.get("retry-after");
+    if (!header) return void 0;
+    const asInt = Number(header);
+    let ms;
+    if (!Number.isNaN(asInt)) {
+      ms = asInt * 1e3;
+    } else {
+      const date = Date.parse(header);
+      if (Number.isNaN(date)) return void 0;
+      ms = date - Date.now();
+    }
+    if (ms < 0) ms = 0;
+    return Math.min(ms, this.maxBackoffMs);
+  }
+  safeDeprecation(message) {
+    try {
+      this.onDeprecation(message);
+    } catch {
+    }
+  }
+  async toError(res) {
+    const requestId = res.headers.get("x-request-id") ?? res.headers.get("x-cavs-request-id") ?? void 0;
+    const retryAfterMs = this.retryAfterMs(res);
+    let body;
+    try {
+      const text = await res.text();
+      body = text ? JSON.parse(text) : void 0;
+    } catch {
+      body = void 0;
+    }
+    return toCAVSError(res.status, body, { requestId, retryAfterMs });
+  }
+  async parseJson(res) {
+    if (res.status === 204) {
+      return void 0;
+    }
+    const text = await res.text();
+    if (!text) {
+      return void 0;
+    }
+    try {
+      return JSON.parse(text);
+    } catch (err) {
+      throw new CAVSError("Failed to parse CAVS response as JSON", { cause: err });
+    }
+  }
+};
+
+// src/uri.ts
+var uri_exports = {};
+__export(uri_exports, {
+  InvalidURIError: () => InvalidURIError,
+  format: () => format,
+  parse: () => parse
+});
+var SCHEME = "cavs://";
+var OID_RE = /^[0-9a-f]{64}$/;
+var SHA_MARKER = "@sha256:";
+var InvalidURIError = class extends CAVSError {
+};
+function parse(uri) {
+  if (typeof uri !== "string" || !uri.startsWith(SCHEME)) {
+    throw new InvalidURIError(`Invalid cavs:// URI: wrong scheme (${redact(uri)})`);
+  }
+  const rest = uri.slice(SCHEME.length);
+  const segments = rest.split("/");
+  if (segments.length !== 4) {
+    throw new InvalidURIError(
+      `Invalid cavs:// URI: expected org/project/kind/name, got ${segments.length} segment(s)`
+    );
+  }
+  const [org, project, kind, last] = segments;
+  if (!org || !project || !kind || !last) {
+    throw new InvalidURIError("Invalid cavs:// URI: empty path segment");
+  }
+  const shaIdx = last.indexOf(SHA_MARKER);
+  if (shaIdx !== -1) {
+    const name2 = last.slice(0, shaIdx);
+    const oid = last.slice(shaIdx + SHA_MARKER.length);
+    if (!name2) {
+      throw new InvalidURIError("Invalid cavs:// URI: empty name");
+    }
+    if (name2.includes(":")) {
+      throw new InvalidURIError("Invalid cavs:// URI: cannot specify both version and oid");
+    }
+    if (!OID_RE.test(oid)) {
+      throw new InvalidURIError("Invalid cavs:// URI: oid must be 64 lowercase hex chars");
+    }
+    return { org, project, kind, name: name2, version: null, oid, immutable: true };
+  }
+  const colonIdx = last.indexOf(":");
+  if (colonIdx === -1) {
+    throw new InvalidURIError("Invalid cavs:// URI: missing version or @sha256:oid");
+  }
+  const name = last.slice(0, colonIdx);
+  const version = last.slice(colonIdx + 1);
+  if (!name) {
+    throw new InvalidURIError("Invalid cavs:// URI: empty name");
+  }
+  if (!version) {
+    throw new InvalidURIError("Invalid cavs:// URI: empty version");
+  }
+  return { org, project, kind, name, version, oid: null, immutable: false };
+}
+function format(parsed) {
+  const { org, project, kind, name, version, oid } = parsed;
+  if (!org || !project || !kind || !name) {
+    throw new InvalidURIError("Cannot format cavs:// URI: missing required field");
+  }
+  if (oid) {
+    if (version) {
+      throw new InvalidURIError("Cannot format cavs:// URI: both version and oid provided");
+    }
+    if (!OID_RE.test(oid)) {
+      throw new InvalidURIError("Cannot format cavs:// URI: oid must be 64 lowercase hex chars");
+    }
+    return `${SCHEME}${org}/${project}/${kind}/${name}${SHA_MARKER}${oid}`;
+  }
+  if (!version) {
+    throw new InvalidURIError("Cannot format cavs:// URI: either version or oid is required");
+  }
+  return `${SCHEME}${org}/${project}/${kind}/${name}:${version}`;
+}
+function redact(uri) {
+  if (typeof uri !== "string") {
+    return String(uri);
+  }
+  return uri.length > 40 ? `${uri.slice(0, 40)}\u2026` : uri;
+}
+
+// src/resources/artifacts.ts
+import { randomUUID } from "crypto";
+
+// src/transfer.ts
+import { createHash } from "crypto";
+import { createReadStream, createWriteStream } from "fs";
+import * as fs from "fs/promises";
+import * as path from "path";
+import { Readable, Transform } from "stream";
+import { pipeline } from "stream/promises";
+async function sha256File(filePath, opts = {}) {
+  throwIfAborted(opts.signal);
+  const hash = createHash("sha256");
+  let size = 0;
+  const stream = createReadStream(filePath, { highWaterMark: opts.highWaterMark });
+  await new Promise((resolve2, reject) => {
+    const onAbort = () => stream.destroy(abortError(opts.signal));
+    if (opts.signal) {
+      opts.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    stream.on("data", (chunk) => {
+      hash.update(chunk);
+      size += chunk.length;
+      opts.onProgress?.(size);
+    });
+    stream.on("error", (err) => {
+      opts.signal?.removeEventListener("abort", onAbort);
+      reject(err);
+    });
+    stream.on("end", () => {
+      opts.signal?.removeEventListener("abort", onAbort);
+      resolve2();
+    });
+  });
+  return { oid: hash.digest("hex"), size };
+}
+async function collectFiles(root) {
+  const stat2 = await fs.stat(root);
+  if (stat2.isFile()) {
+    return [{ absPath: path.resolve(root), relPath: path.basename(root) }];
+  }
+  if (!stat2.isDirectory()) {
+    throw new UploadError(`Not a regular file or directory: ${root}`);
+  }
+  const out = [];
+  const base = path.resolve(root);
+  async function walk(dir) {
+    const entries = await fs.readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(abs);
+      } else if (entry.isFile()) {
+        const rel = path.relative(base, abs).split(path.sep).join("/");
+        out.push({ absPath: abs, relPath: rel });
+      }
+    }
+  }
+  await walk(base);
+  out.sort((a, b) => a.relPath < b.relPath ? -1 : a.relPath > b.relPath ? 1 : 0);
+  return out;
+}
+async function prepareUpload(root, opts = {}) {
+  const found = await collectFiles(root);
+  const files = [];
+  for (const f of found) {
+    const { oid, size } = await sha256File(f.absPath, {
+      signal: opts.signal,
+      onProgress: (loaded) => opts.onProgress?.({ phase: "hash", path: f.relPath, loaded, total: 0 })
+    });
+    files.push({ ...f, oid, size });
+  }
+  return files;
+}
+function countingReadStream(filePath, onChunk) {
+  const stream = createReadStream(filePath);
+  stream.on("data", (chunk) => onChunk(chunk.length));
+  return stream;
+}
+async function downloadToFile(body, args) {
+  const target = safeJoin(args.destDir, args.relPath);
+  await fs.mkdir(path.dirname(target), { recursive: true });
+  const tmp = path.join(path.dirname(target), `.cavs-download-${args.oid}.part`);
+  if (!body) {
+    throw new DownloadError(`Empty response body while downloading ${args.relPath}`);
+  }
+  const hash = createHash("sha256");
+  let size = 0;
+  const nodeReadable = Readable.fromWeb(body);
+  const hashing = new Transform({
+    transform(chunk, _enc, cb) {
+      hash.update(chunk);
+      size += chunk.length;
+      args.onProgress?.({
+        phase: "download",
+        path: args.relPath,
+        loaded: size,
+        total: args.size ?? 0
+      });
+      cb(null, chunk);
+    }
+  });
+  try {
+    await pipeline(nodeReadable, hashing, createWriteStream(tmp), { signal: args.signal });
+  } catch (err) {
+    await safeUnlink(tmp);
+    throw err instanceof ChecksumError ? err : new DownloadError(`Failed to download ${args.relPath}`, { cause: err });
+  }
+  const digest = hash.digest("hex");
+  if (digest !== args.oid) {
+    await safeUnlink(tmp);
+    throw new ChecksumError(
+      `Checksum mismatch for ${args.relPath}: expected ${args.oid}, got ${digest}`
+    );
+  }
+  await fs.rename(tmp, target);
+  return { path: args.relPath, oid: args.oid, size };
+}
+function safeJoin(destDir, relPath) {
+  if (path.isAbsolute(relPath)) {
+    throw new DownloadError(`Refusing absolute path in artifact: ${relPath}`);
+  }
+  const base = path.resolve(destDir);
+  const target = path.resolve(base, relPath);
+  const withSep = base.endsWith(path.sep) ? base : base + path.sep;
+  if (target !== base && !target.startsWith(withSep)) {
+    throw new DownloadError(`Path traversal detected in artifact member: ${relPath}`);
+  }
+  return target;
+}
+function throwIfAborted(signal) {
+  if (signal?.aborted) {
+    throw abortError(signal);
+  }
+}
+function abortError(signal) {
+  const reason = signal?.reason;
+  return reason instanceof Error ? reason : new Error("Operation aborted");
+}
+async function safeUnlink(p) {
+  try {
+    await fs.unlink(p);
+  } catch {
+  }
+}
+
+// src/resources/artifacts.ts
+var ArtifactsResource = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** `GET /api/v1/artifacts/{id}`. */
+  async get(artifactId, signal) {
+    return this.ctx.http.requestJson({
+      path: `/api/v1/artifacts/${encodeURIComponent(artifactId)}`,
+      signal
+    });
+  }
+  /** `GET /api/v1/artifacts/{id}/versions`. */
+  async versions(artifactId, signal) {
+    return this.ctx.http.requestJson({
+      path: `/api/v1/artifacts/${encodeURIComponent(artifactId)}/versions`,
+      signal
+    });
+  }
+  /** `GET /api/v1/organizations/{org}/artifacts`. */
+  async list(opts = {}) {
+    const org = opts.org ?? this.ctx.defaultOrg;
+    if (!org) {
+      throw new CAVSError("No organization specified for artifacts.list (pass { org } or set CAVS_ORG).");
+    }
+    return this.ctx.http.requestJson({
+      path: `/api/v1/organizations/${encodeURIComponent(org)}/artifacts`,
+      query: { limit: opts.limit, type: opts.type, q: opts.q },
+      signal: opts.signal
+    });
+  }
+  /**
+   * Upload a file or directory as a new artifact version, following the
+   * choreography in CONTRACT.md §5. Streams every object; skips objects that
+   * already exist (dedup); resumable because step 3 re-reports `exists`.
+   */
+  async upload(opts) {
+    const repo = opts.project;
+    const files = await prepareUpload(opts.path, {
+      signal: opts.signal,
+      onProgress: opts.onProgress
+    });
+    if (files.length === 0) {
+      throw new UploadError(`Nothing to upload: ${opts.path} contains no files`);
+    }
+    const idempotencyKey = opts.idempotencyKey ?? `upload:${repo}:${opts.kind}:${opts.name}:${opts.version}`;
+    const repoPath = `/api/v1/repositories/${encodeURIComponent(repo)}`;
+    const session = await this.ctx.http.requestJson({
+      method: "POST",
+      path: `${repoPath}/uploads`,
+      idempotencyKey,
+      body: { expected_objects: files.length },
+      signal: opts.signal
+    });
+    const sessionId = session.session_id ?? session.id;
+    if (!sessionId) {
+      throw new UploadError("Upload session response did not include a session id");
+    }
+    const sessionPath = `${repoPath}/uploads/${encodeURIComponent(sessionId)}`;
+    const uniqueObjects = dedupeObjects(files);
+    const authResults = await this.ctx.http.requestJson({
+      method: "POST",
+      path: `${sessionPath}/objects`,
+      body: { objects: uniqueObjects.map((f) => ({ oid: f.oid, size: f.size })) },
+      signal: opts.signal
+    });
+    const authByOid = new Map(authResults.map((r) => [r.oid, r]));
+    const uploaded = [];
+    const doneOids = /* @__PURE__ */ new Set();
+    for (const file of files) {
+      const entry = authByOid.get(file.oid);
+      if (!entry) {
+        throw new UploadError(`Server did not return an authorization for oid ${file.oid}`);
+      }
+      if (entry.error) {
+        throw new UploadError(`Upload rejected for ${file.relPath}: ${entry.error}`);
+      }
+      const deduplicated = entry.exists === true;
+      if (!deduplicated && !doneOids.has(file.oid)) {
+        if (!entry.upload_url) {
+          throw new UploadError(`Missing upload URL for ${file.relPath}`);
+        }
+        await this.putObject(entry.upload_url, file, opts);
+        await this.ctx.http.requestJson({
+          method: "POST",
+          path: `${sessionPath}/objects/${encodeURIComponent(file.oid)}/complete`,
+          body: { size: file.size },
+          signal: opts.signal
+        });
+      }
+      doneOids.add(file.oid);
+      uploaded.push({
+        path: file.relPath,
+        oid: file.oid,
+        size: file.size,
+        deduplicated
+      });
+    }
+    const finalize = await this.ctx.http.requestJson({
+      method: "POST",
+      path: `${sessionPath}/finalize`,
+      idempotencyKey: `${idempotencyKey}:finalize`,
+      body: {
+        name: opts.name,
+        kind: opts.kind,
+        version: opts.version,
+        metadata: opts.metadata ?? {},
+        files: files.map((f) => ({ path: f.relPath, oid: f.oid, size: f.size }))
+      },
+      signal: opts.signal
+    });
+    const logical = finalize.logical_bytes ?? files.reduce((n, f) => n + f.size, 0);
+    return {
+      artifactId: finalize.artifact_id,
+      reference: finalize.artifact_reference ?? finalize.reference ?? format({
+        org: opts.org ?? this.ctx.defaultOrg ?? "org",
+        project: opts.project,
+        kind: opts.kind,
+        name: opts.name,
+        version: opts.version
+      }),
+      version: finalize.version,
+      sha256: finalize.sha256,
+      logicalBytes: logical,
+      physicalBytes: finalize.physical_bytes ?? logical,
+      deduplicatedBytes: finalize.deduplicated_bytes ?? 0,
+      deduplicationRatio: finalize.deduplication_ratio ?? 0,
+      files: uploaded
+    };
+  }
+  async putObject(uploadUrl, file, opts) {
+    const res = await this.ctx.http.sendStream(uploadUrl, {
+      method: "PUT",
+      headers: { "Content-Length": String(file.size) },
+      bodyFactory: () => countingReadStream(file.absPath, (bytes) => {
+        this.reportUpload(file, bytes, opts);
+      }),
+      init: { duplex: "half" },
+      signal: opts.signal
+    });
+    if (!res.ok) {
+      throw new UploadError(
+        `Presigned upload failed for ${file.relPath} (status ${res.status})`,
+        { status: res.status }
+      );
+    }
+  }
+  reportUpload(file, bytes, opts) {
+    if (!opts.onProgress) return;
+    const state = this.uploadProgress ??= /* @__PURE__ */ new Map();
+    const loaded = (state.get(file.oid) ?? 0) + bytes;
+    state.set(file.oid, loaded);
+    opts.onProgress({ phase: "upload", path: file.relPath, loaded, total: file.size });
+  }
+  uploadProgress;
+  /**
+   * Download an artifact by its `cavs://` reference into `opts.dest`, verifying
+   * each object's sha256 and writing atomically (CONTRACT.md §5).
+   */
+  async download(reference, opts) {
+    parse(reference);
+    const resolved = await this.ctx.http.requestJson({
+      path: "/api/v1/resolve",
+      query: { uri: reference },
+      signal: opts.signal
+    });
+    const repo = resolved.repository ?? resolved.repository_id ?? resolved.repo;
+    if (!repo) {
+      throw new CAVSError("Resolve response did not include a repository for the reference");
+    }
+    const files = resolved.files ?? [];
+    if (files.length === 0) {
+      throw new CAVSError(`No files found for reference ${reference}`);
+    }
+    const oids = [...new Set(files.map((f) => f.oid))];
+    const auth = await this.ctx.http.requestJson({
+      method: "POST",
+      path: `/api/v1/repositories/${encodeURIComponent(repo)}/downloads/authorize`,
+      body: { oids },
+      signal: opts.signal
+    });
+    const urlByOid = new Map(auth.map((a) => [a.oid, a]));
+    const results = [];
+    for (const file of files) {
+      const entry = urlByOid.get(file.oid);
+      if (!entry || entry.error || !entry.download_url) {
+        throw new CAVSError(
+          `Download authorization failed for ${file.path}${entry?.error ? `: ${entry.error}` : ""}`
+        );
+      }
+      const res = await this.ctx.http.openStream(entry.download_url, { signal: opts.signal });
+      const written = await downloadToFile(res.body, {
+        destDir: opts.dest,
+        relPath: file.path,
+        oid: file.oid,
+        size: file.size,
+        onProgress: opts.onProgress,
+        signal: opts.signal
+      });
+      results.push(written);
+    }
+    return { dest: opts.dest, files: results };
+  }
+};
+function dedupeObjects(files) {
+  const seen = /* @__PURE__ */ new Set();
+  const out = [];
+  for (const f of files) {
+    if (!seen.has(f.oid)) {
+      seen.add(f.oid);
+      out.push(f);
+    }
+  }
+  return out;
+}
+
+// src/resources/snapshots.ts
+var SnapshotsResource = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** `GET /api/v1/repositories/{repo}/snapshots`. */
+  async list(project, signal) {
+    return this.ctx.http.requestJson({
+      path: `/api/v1/repositories/${encodeURIComponent(project)}/snapshots`,
+      signal
+    });
+  }
+  /** `POST /api/v1/repositories/{repo}/snapshots`. */
+  async create(project, opts = {}) {
+    return this.ctx.http.requestJson({
+      method: "POST",
+      path: `/api/v1/repositories/${encodeURIComponent(project)}/snapshots`,
+      idempotencyKey: opts.idempotencyKey,
+      body: { message: opts.message, metadata: opts.metadata ?? {} },
+      signal: opts.signal
+    });
+  }
+};
+
+// src/resources/releases.ts
+var ReleasesResource = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** `GET /api/v1/repositories/{repo}/releases`. */
+  async list(project, signal) {
+    return this.ctx.http.requestJson({
+      path: `/api/v1/repositories/${encodeURIComponent(project)}/releases`,
+      signal
+    });
+  }
+  /** `GET /api/v1/repositories/{repo}/releases/{tag}`. */
+  async get(project, tag, signal) {
+    return this.ctx.http.requestJson({
+      path: `/api/v1/repositories/${encodeURIComponent(project)}/releases/${encodeURIComponent(tag)}`,
+      signal
+    });
+  }
+};
+
+// src/resources/runs.ts
+var RunsResource = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  base(project) {
+    return `/api/v1/repositories/${encodeURIComponent(project)}/runs`;
+  }
+  /** `POST /api/v1/repositories/{repo}/runs`. */
+  async create(project, opts) {
+    return this.ctx.http.requestJson({
+      method: "POST",
+      path: this.base(project),
+      idempotencyKey: opts.idempotencyKey,
+      body: {
+        name: opts.name,
+        system: opts.system,
+        external_id: opts.externalId,
+        git_commit: opts.gitCommit,
+        pipeline: opts.pipeline,
+        environment: opts.environment,
+        status: opts.status,
+        metadata: opts.metadata ?? {}
+      },
+      signal: opts.signal
+    });
+  }
+  /** `GET /api/v1/repositories/{repo}/runs`. */
+  async list(project, signal) {
+    return this.ctx.http.requestJson({ path: this.base(project), signal });
+  }
+  /** `GET /api/v1/repositories/{repo}/runs/{run}`. */
+  async get(project, runId, signal) {
+    return this.ctx.http.requestJson({
+      path: `${this.base(project)}/${encodeURIComponent(runId)}`,
+      signal
+    });
+  }
+  /** `PATCH /api/v1/repositories/{repo}/runs/{run}`. */
+  async update(project, runId, opts) {
+    return this.ctx.http.requestJson({
+      method: "PATCH",
+      path: `${this.base(project)}/${encodeURIComponent(runId)}`,
+      idempotencyKey: opts.idempotencyKey,
+      body: { status: opts.status, ended_at: opts.endedAt, metadata: opts.metadata },
+      signal: opts.signal
+    });
+  }
+  /** `POST /api/v1/repositories/{repo}/runs/{run}/artifacts` — record lineage. */
+  async addArtifacts(project, runId, artifacts, opts = {}) {
+    return this.ctx.http.requestJson({
+      method: "POST",
+      path: `${this.base(project)}/${encodeURIComponent(runId)}/artifacts`,
+      idempotencyKey: opts.idempotencyKey,
+      body: { artifacts },
+      signal: opts.signal
+    });
+  }
+};
+
+// src/resources/lineage.ts
+var LineageResource = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** `GET /api/v1/repositories/{repo}/graph`. */
+  async graph(project, signal) {
+    return this.ctx.http.requestJson({
+      path: `/api/v1/repositories/${encodeURIComponent(project)}/graph`,
+      signal
+    });
+  }
+  /** `POST /api/v1/repositories/{repo}/graph/edges`. */
+  async addEdge(project, opts) {
+    return this.ctx.http.requestJson({
+      method: "POST",
+      path: `/api/v1/repositories/${encodeURIComponent(project)}/graph/edges`,
+      idempotencyKey: opts.idempotencyKey,
+      body: {
+        from_type: opts.fromType,
+        from_key: opts.fromKey,
+        to_type: opts.toType,
+        to_key: opts.toKey,
+        relation: opts.relation,
+        metadata: opts.metadata ?? {}
+      },
+      signal: opts.signal
+    });
+  }
+};
+
+// src/resources/usage.ts
+var UsageResource = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  /** `GET /api/v1/organizations/{org}/usage`. */
+  async get(opts = {}) {
+    const org = opts.org ?? this.ctx.defaultOrg;
+    if (!org) {
+      throw new CAVSError("No organization specified for usage.get (pass { org } or set CAVS_ORG).");
+    }
+    return this.ctx.http.requestJson({
+      path: `/api/v1/organizations/${encodeURIComponent(org)}/usage`,
+      signal: opts.signal
+    });
+  }
+};
+
+// src/resources/serviceAccounts.ts
+var ServiceAccountsResource = class {
+  constructor(ctx) {
+    this.ctx = ctx;
+  }
+  ctx;
+  org(explicit) {
+    const org = explicit ?? this.ctx.defaultOrg;
+    if (!org) {
+      throw new CAVSError("No organization specified (pass { org } or set CAVS_ORG).");
+    }
+    return org;
+  }
+  base(org) {
+    return `/api/v1/organizations/${encodeURIComponent(this.org(org))}/service-accounts`;
+  }
+  /** `GET …/service-accounts`. */
+  async list(opts = {}) {
+    return this.ctx.http.requestJson({ path: this.base(opts.org), signal: opts.signal });
+  }
+  /** `POST …/service-accounts`. */
+  async create(opts) {
+    return this.ctx.http.requestJson({
+      method: "POST",
+      path: this.base(opts.org),
+      body: {
+        name: opts.name,
+        description: opts.description,
+        scopes: opts.scopes,
+        repository_ids: opts.repositoryIds,
+        environment: opts.environment
+      },
+      signal: opts.signal
+    });
+  }
+  /** `PATCH …/service-accounts/{id}` — enable/disable, edit scopes/repos. */
+  async update(id, patch, opts = {}) {
+    return this.ctx.http.requestJson({
+      method: "PATCH",
+      path: `${this.base(opts.org)}/${encodeURIComponent(id)}`,
+      body: {
+        disabled: patch.disabled,
+        scopes: patch.scopes,
+        repository_ids: patch.repositoryIds
+      },
+      signal: opts.signal
+    });
+  }
+  /** `DELETE …/service-accounts/{id}`. */
+  async delete(id, opts = {}) {
+    await this.ctx.http.requestJson({
+      method: "DELETE",
+      path: `${this.base(opts.org)}/${encodeURIComponent(id)}`,
+      signal: opts.signal
+    });
+  }
+  /** `POST …/service-accounts/{id}/keys` — the secret is returned once. */
+  async createKey(id, opts = {}) {
+    return this.ctx.http.requestJson({
+      method: "POST",
+      path: `${this.base(opts.org)}/${encodeURIComponent(id)}/keys`,
+      signal: opts.signal
+    });
+  }
+  /** `POST …/service-accounts/{id}/keys/{key}/rotate`. */
+  async rotateKey(id, keyId, opts = {}) {
+    return this.ctx.http.requestJson({
+      method: "POST",
+      path: `${this.base(opts.org)}/${encodeURIComponent(id)}/keys/${encodeURIComponent(keyId)}/rotate`,
+      signal: opts.signal
+    });
+  }
+  /** `DELETE …/service-accounts/{id}/keys/{key}`. */
+  async deleteKey(id, keyId, opts = {}) {
+    await this.ctx.http.requestJson({
+      method: "DELETE",
+      path: `${this.base(opts.org)}/${encodeURIComponent(id)}/keys/${encodeURIComponent(keyId)}`,
+      signal: opts.signal
+    });
+  }
+};
+
+// src/client.ts
+var DEFAULT_API = "https://api.cavs.dev";
+var CAVS = class _CAVS {
+  http;
+  defaultOrg;
+  artifacts;
+  snapshots;
+  releases;
+  runs;
+  lineage;
+  usage;
+  serviceAccounts;
+  constructor(options = {}) {
+    const token = resolveToken(options.token);
+    const api = (options.api ?? process.env.CAVS_API ?? DEFAULT_API).replace(/\/+$/, "");
+    this.defaultOrg = options.org ?? process.env.CAVS_ORG;
+    this.http = new HttpClient({
+      baseUrl: api,
+      token,
+      fetch: options.fetch,
+      telemetry: {
+        integration: options.integration,
+        integrationVersion: options.integrationVersion,
+        runId: options.runId
+      },
+      timeoutMs: options.timeoutMs,
+      maxRetries: options.maxRetries,
+      onDeprecation: options.onDeprecation,
+      retryBaseMs: options.retryBaseMs,
+      sleepImpl: options.sleepImpl
+    });
+    const ctx = { http: this.http, defaultOrg: this.defaultOrg };
+    this.artifacts = new ArtifactsResource(ctx);
+    this.snapshots = new SnapshotsResource(ctx);
+    this.releases = new ReleasesResource(ctx);
+    this.runs = new RunsResource(ctx);
+    this.lineage = new LineageResource(ctx);
+    this.usage = new UsageResource(ctx);
+    this.serviceAccounts = new ServiceAccountsResource(ctx);
+  }
+  /** Construct a client from the environment (`CAVS_TOKEN`, `CAVS_API`, `CAVS_ORG`). */
+  static fromEnv(options = {}) {
+    return new _CAVS(options);
+  }
+  /** Resolve the org to use for org-scoped calls. */
+  resolveOrg(explicit) {
+    const org = explicit ?? this.defaultOrg;
+    if (!org) {
+      throw new CAVSError(
+        "No organization specified. Pass { org } to the call or the constructor, or set CAVS_ORG."
+      );
+    }
+    return org;
+  }
+  /** `GET /api/v1/users/me` — the authenticated identity. */
+  async me(signal) {
+    return this.http.requestJson({ path: "/api/v1/users/me", signal });
+  }
+  /** `GET /api/v1/search?q=` — cross-org search. */
+  async search(q, signal) {
+    return this.http.requestJson({ path: "/api/v1/search", query: { q }, signal });
+  }
+  /** `GET /api/v1/resolve?uri=` — resolve a `cavs://` reference to concrete objects. */
+  async resolve(reference, signal) {
+    parse(reference);
+    return this.http.requestJson({ path: "/api/v1/resolve", query: { uri: reference }, signal });
+  }
+  /** `GET /api/v1/organizations/{org}/repositories`. */
+  async listRepositories(org, signal) {
+    const slug = this.resolveOrg(org);
+    return this.http.requestJson({
+      path: `/api/v1/organizations/${encodeURIComponent(slug)}/repositories`,
+      signal
+    });
+  }
+};
+export {
+  AuthenticationError,
+  AuthorizationError,
+  CAVS,
+  CAVSError,
+  ChecksumError,
+  ConflictError,
+  DEFAULT_API,
+  DownloadError,
+  InvalidURIError,
+  NotFoundError,
+  QuotaExceededError,
+  RateLimitError,
+  TemporaryServiceError,
+  UploadError,
+  VERSION,
+  sha256File,
+  uri_exports as uri
+};
+//# sourceMappingURL=index.js.map