@cavsnode/cavs-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,735 @@
+/**
+ * Telemetry headers sent on every request (CONTRACT.md §7).
+ *
+ *   User-Agent: cavs-node/<version>
+ *   X-CAVS-Client: javascript-sdk
+ *   X-CAVS-Integration: <javascript-sdk by default; integrations override>
+ *   X-CAVS-Integration-Version: <version>
+ *   X-CAVS-Run-ID: <optional correlation id>
+ */
+/** The SDK version, embedded in the User-Agent and integration-version headers. */
+declare const VERSION = "0.1.0";
+interface TelemetryOptions {
+    /** Integration id; defaults to {@link CLIENT_ID}. Integrations built on top override it. */
+    integration?: string;
+    /** Version of the integration; defaults to the SDK {@link VERSION}. */
+    integrationVersion?: string;
+    /** Optional run / correlation id, surfaced as `X-CAVS-Run-ID`. */
+    runId?: string;
+}
+
+/**
+ * HTTP transport built on the global `fetch` (CONTRACT.md §7, §8).
+ *
+ * Responsibilities:
+ *  - Attach auth + telemetry headers and an optional Idempotency-Key.
+ *  - Retry <= `maxRetries` times on 429 / 5xx / network errors with exponential
+ *    backoff + jitter, honouring `Retry-After` (capped ~30s).
+ *  - Enforce a request timeout via AbortController and propagate external
+ *    cancellation.
+ *  - Bound redirects (<= 5).
+ *  - Map the server error envelope to a typed {@link CAVSError}.
+ *  - Never log tokens or presigned URLs.
+ */
+
+/** Injectable fetch implementation (defaults to the global `fetch`). */
+type FetchLike = typeof fetch;
+/** The request-body type accepted by `fetch` (derived to avoid needing the DOM lib). */
+type BodyInit = NonNullable<RequestInit["body"]>;
+/** A no-arg factory that produces a fresh request body — required so streamed
+ * bodies can be rewound and resent on retry. */
+type BodyFactory = () => BodyInit;
+interface HttpClientOptions {
+    baseUrl: string;
+    token: string;
+    fetch?: FetchLike;
+    telemetry?: TelemetryOptions;
+    /** Max retries on 429/5xx/network (default 4). Total attempts = maxRetries + 1. */
+    maxRetries?: number;
+    /** Max redirects to follow (default 5). */
+    maxRedirects?: number;
+    /** Per-attempt timeout in ms (default 30000). */
+    timeoutMs?: number;
+    /** Base backoff in ms (default 200). Set to 0 in tests to disable delays. */
+    retryBaseMs?: number;
+    /** Cap on any single backoff/Retry-After wait in ms (default 30000). */
+    maxBackoffMs?: number;
+    /** Called (never throws) when the server sends `X-CAVS-Deprecation`. */
+    onDeprecation?: (message: string) => void;
+    /** Injectable sleep (for tests). */
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+interface RequestOptions {
+    method?: string;
+    path: string;
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+    headers?: Record<string, string>;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+declare class HttpClient {
+    private readonly baseUrl;
+    private readonly token;
+    private readonly fetchImpl;
+    private readonly telemetry;
+    readonly maxRetries: number;
+    readonly maxRedirects: number;
+    readonly timeoutMs: number;
+    private readonly retryBaseMs;
+    private readonly maxBackoffMs;
+    private readonly onDeprecation;
+    private readonly sleepImpl;
+    constructor(opts: HttpClientOptions);
+    /** Build the standard header set for a control-plane request. */
+    private baseHeaders;
+    private buildUrl;
+    /** Perform a JSON control-plane request with retries and typed errors. */
+    requestJson<T = unknown>(opts: RequestOptions): Promise<T>;
+    /**
+     * 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.
+     */
+    sendStream(url: string, opts: {
+        method: string;
+        bodyFactory: BodyFactory;
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+        /** Extra fetch init (e.g. `duplex: "half"`). */
+        init?: RequestInit;
+    }): Promise<Response>;
+    /** Open a streaming GET (presigned download). Returns the raw Response. */
+    openStream(url: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<Response>;
+    private executeWithRetry;
+    /** Follow redirects manually, bounded by {@link maxRedirects}. */
+    private fetchWithRedirects;
+    private armSignal;
+    private backoff;
+    private retryAfterMs;
+    private safeDeprecation;
+    private toError;
+    private parseJson;
+}
+
+/**
+ * Public type definitions for the CAVS SDK.
+ *
+ * Wire responses use snake_case; the SDK surfaces camelCase. The resource
+ * modules perform the mapping. Fields marked optional may be absent depending on
+ * the endpoint and server version.
+ */
+/** Result of `GET /api/v1/users/me`. */
+interface Me {
+    id: string;
+    email?: string;
+    name?: string;
+    /** Organizations the caller belongs to. */
+    organizations?: Org[];
+    /** Present when the token is a service account. */
+    serviceAccount?: {
+        id: string;
+        name?: string;
+        org?: string;
+    };
+}
+/** An organization. */
+interface Org {
+    id: string;
+    slug: string;
+    name?: string;
+}
+/** A repository (a "project"). */
+interface Repo {
+    id: string;
+    slug: string;
+    name?: string;
+    org?: string;
+    generation?: number;
+}
+/** An artifact (a named, versioned bundle of objects). */
+interface Artifact {
+    id: string;
+    name: string;
+    kind: string;
+    project?: string;
+    org?: string;
+    reference?: string;
+    latestVersion?: string;
+    metadata?: Record<string, unknown>;
+}
+/** One version of an artifact. */
+interface ArtifactVersion {
+    version: string;
+    sha256: string;
+    reference?: string;
+    createdAt?: string;
+    metadata?: Record<string, unknown>;
+    files?: ArtifactFile[];
+}
+/** A single stored object within an artifact version. */
+interface ArtifactFile {
+    path: string;
+    oid: string;
+    size: number;
+}
+/** Dedup + identity result returned by a completed upload (finalize). */
+interface UploadResult {
+    artifactId: string;
+    /** Canonical `cavs://` reference for the created version. */
+    reference: string;
+    version: string;
+    /** sha256 of the artifact (its manifest / root oid). */
+    sha256: string;
+    logicalBytes: number;
+    physicalBytes: number;
+    deduplicatedBytes: number;
+    deduplicationRatio: number;
+    /** Per-file breakdown of what was uploaded vs. deduplicated. */
+    files: UploadedFile[];
+}
+/** Per-object upload outcome. */
+interface UploadedFile {
+    path: string;
+    oid: string;
+    size: number;
+    /** `true` when the object already existed server-side and the PUT was skipped. */
+    deduplicated: boolean;
+}
+/** Result of a completed download. */
+interface DownloadResult {
+    /** Destination directory the files were written to. */
+    dest: string;
+    files: DownloadedFile[];
+}
+/** Per-object download outcome. */
+interface DownloadedFile {
+    path: string;
+    oid: string;
+    size: number;
+}
+/** A repository snapshot. */
+interface Snapshot {
+    id: string;
+    generation?: number;
+    createdAt?: string;
+    message?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A named release. */
+interface Release {
+    tag: string;
+    snapshotId?: string;
+    createdAt?: string;
+    notes?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A pipeline run. */
+interface Run {
+    id: string;
+    status?: string;
+    name?: string;
+    createdAt?: string;
+    updatedAt?: string;
+    metadata?: Record<string, unknown>;
+}
+/** A lineage edge between two nodes in the artifact graph. */
+interface LineageEdge {
+    id?: string;
+    from: string;
+    to: string;
+    relation?: string;
+    metadata?: Record<string, unknown>;
+}
+/** The lineage graph for a repository. */
+interface LineageGraph {
+    nodes: Array<Record<string, unknown>>;
+    edges: LineageEdge[];
+}
+/** Usage / billing snapshot for an org. */
+interface Usage {
+    org?: string;
+    logicalBytes?: number;
+    physicalBytes?: number;
+    deduplicatedBytes?: number;
+    deduplicationRatio?: number;
+    artifactCount?: number;
+    [key: string]: unknown;
+}
+/** A service account. */
+interface ServiceAccount {
+    id: string;
+    name: string;
+    org?: string;
+    disabled?: boolean;
+    createdAt?: string;
+}
+/** A service-account API key. The `secret` is only returned once, on creation/rotation. */
+interface ServiceAccountKey {
+    id: string;
+    serviceAccountId?: string;
+    /** Present only in the create/rotate response. */
+    secret?: string;
+    createdAt?: string;
+    lastUsedAt?: string;
+}
+/** Progress event emitted during upload/download/hashing. */
+interface ProgressEvent {
+    phase: "hash" | "upload" | "download";
+    /** The relative path of the file being processed. */
+    path: string;
+    /** Bytes processed so far for this file. */
+    loaded: number;
+    /** Total bytes for this file, when known. */
+    total: number;
+}
+/** A progress callback. */
+type ProgressCallback = (event: ProgressEvent) => void;
+
+/**
+ * Artifacts resource — the upload/download data plane plus artifact discovery
+ * (CONTRACT.md §4, §5).
+ *
+ * `project` is an alias for `repository`: the caller passes `project` (a repo
+ * slug or id) and it is used directly as `{repo}` in the repository-scoped
+ * endpoints. `org` is only needed for org-scoped listing.
+ */
+
+interface UploadOptions {
+    /** Local file or directory to upload. */
+    path: string;
+    /** Project (repository slug or id) to upload into. */
+    project: string;
+    /** Artifact name. */
+    name: string;
+    /** Artifact kind (e.g. `model`, `dataset`, `game-build`). */
+    kind: string;
+    /** Logical version tag. */
+    version: string;
+    /** Arbitrary metadata attached to the version. */
+    metadata?: Record<string, unknown>;
+    /** Organization slug (only recorded; defaults to the client's org). */
+    org?: string;
+    /** Stable idempotency key; a deterministic one is derived when omitted. */
+    idempotencyKey?: string;
+    /** Progress callback (hashing + upload phases). */
+    onProgress?: ProgressCallback;
+    /** Cancellation signal. */
+    signal?: AbortSignal;
+}
+interface DownloadOptions {
+    /** Destination directory. */
+    dest: string;
+    /** Organization slug override (defaults to the reference's org). */
+    org?: string;
+    /** Progress callback (download phase). */
+    onProgress?: ProgressCallback;
+    /** Cancellation signal. */
+    signal?: AbortSignal;
+}
+declare class ArtifactsResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    /** `GET /api/v1/artifacts/{id}`. */
+    get(artifactId: string, signal?: AbortSignal): Promise<Artifact>;
+    /** `GET /api/v1/artifacts/{id}/versions`. */
+    versions(artifactId: string, signal?: AbortSignal): Promise<ArtifactVersion[]>;
+    /** `GET /api/v1/organizations/{org}/artifacts`. */
+    list(opts?: {
+        org?: string;
+        limit?: number;
+        type?: string;
+        q?: string;
+        signal?: AbortSignal;
+    }): Promise<Artifact[]>;
+    /**
+     * 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`.
+     */
+    upload(opts: UploadOptions): Promise<UploadResult>;
+    private putObject;
+    private reportUpload;
+    private uploadProgress?;
+    /**
+     * Download an artifact by its `cavs://` reference into `opts.dest`, verifying
+     * each object's sha256 and writing atomically (CONTRACT.md §5).
+     */
+    download(reference: string, opts: DownloadOptions): Promise<DownloadResult>;
+}
+
+/** Snapshots resource (CONTRACT.md §4). `project` is a repository slug/id. */
+
+interface CreateSnapshotOptions {
+    message?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+declare class SnapshotsResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    /** `GET /api/v1/repositories/{repo}/snapshots`. */
+    list(project: string, signal?: AbortSignal): Promise<Snapshot[]>;
+    /** `POST /api/v1/repositories/{repo}/snapshots`. */
+    create(project: string, opts?: CreateSnapshotOptions): Promise<Snapshot>;
+}
+
+/** Releases resource (CONTRACT.md §4). `project` is a repository slug/id. */
+
+declare class ReleasesResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    /** `GET /api/v1/repositories/{repo}/releases`. */
+    list(project: string, signal?: AbortSignal): Promise<Release[]>;
+    /** `GET /api/v1/repositories/{repo}/releases/{tag}`. */
+    get(project: string, tag: string, signal?: AbortSignal): Promise<Release>;
+}
+
+/** Runs resource (CONTRACT.md §4 — runs & lineage). `project` is a repo slug/id. */
+
+interface CreateRunOptions {
+    name: string;
+    system: string;
+    externalId?: string;
+    gitCommit?: string;
+    pipeline?: string;
+    environment?: string;
+    status?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+interface UpdateRunOptions {
+    status?: string;
+    endedAt?: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+/** An artifact association to record on a run (creates lineage edges). */
+interface RunArtifact {
+    oid?: string;
+    reference?: string;
+    role: "input" | "output";
+    [key: string]: unknown;
+}
+declare class RunsResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    private base;
+    /** `POST /api/v1/repositories/{repo}/runs`. */
+    create(project: string, opts: CreateRunOptions): Promise<Run>;
+    /** `GET /api/v1/repositories/{repo}/runs`. */
+    list(project: string, signal?: AbortSignal): Promise<Run[]>;
+    /** `GET /api/v1/repositories/{repo}/runs/{run}`. */
+    get(project: string, runId: string, signal?: AbortSignal): Promise<Run>;
+    /** `PATCH /api/v1/repositories/{repo}/runs/{run}`. */
+    update(project: string, runId: string, opts: UpdateRunOptions): Promise<Run>;
+    /** `POST /api/v1/repositories/{repo}/runs/{run}/artifacts` — record lineage. */
+    addArtifacts(project: string, runId: string, artifacts: RunArtifact[], opts?: {
+        idempotencyKey?: string;
+        signal?: AbortSignal;
+    }): Promise<unknown>;
+}
+
+/** Lineage graph resource (CONTRACT.md §4). `project` is a repository slug/id. */
+
+interface AddEdgeOptions {
+    fromType: string;
+    fromKey: string;
+    toType: string;
+    toKey: string;
+    relation: string;
+    metadata?: Record<string, unknown>;
+    idempotencyKey?: string;
+    signal?: AbortSignal;
+}
+declare class LineageResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    /** `GET /api/v1/repositories/{repo}/graph`. */
+    graph(project: string, signal?: AbortSignal): Promise<LineageGraph>;
+    /** `POST /api/v1/repositories/{repo}/graph/edges`. */
+    addEdge(project: string, opts: AddEdgeOptions): Promise<LineageEdge>;
+}
+
+/** Usage / dedup-stats resource (CONTRACT.md §4). */
+
+declare class UsageResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    /** `GET /api/v1/organizations/{org}/usage`. */
+    get(opts?: {
+        org?: string;
+        signal?: AbortSignal;
+    }): Promise<Usage>;
+}
+
+/** Service accounts resource (org admin, CONTRACT.md §4). */
+
+interface CreateServiceAccountOptions {
+    name: string;
+    description?: string;
+    scopes?: string[];
+    repositoryIds?: string[];
+    environment?: string;
+    org?: string;
+    signal?: AbortSignal;
+}
+declare class ServiceAccountsResource {
+    private readonly ctx;
+    constructor(ctx: ClientContext);
+    private org;
+    private base;
+    /** `GET …/service-accounts`. */
+    list(opts?: {
+        org?: string;
+        signal?: AbortSignal;
+    }): Promise<ServiceAccount[]>;
+    /** `POST …/service-accounts`. */
+    create(opts: CreateServiceAccountOptions): Promise<ServiceAccount>;
+    /** `PATCH …/service-accounts/{id}` — enable/disable, edit scopes/repos. */
+    update(id: string, patch: {
+        disabled?: boolean;
+        scopes?: string[];
+        repositoryIds?: string[];
+    }, opts?: {
+        org?: string;
+        signal?: AbortSignal;
+    }): Promise<ServiceAccount>;
+    /** `DELETE …/service-accounts/{id}`. */
+    delete(id: string, opts?: {
+        org?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+    /** `POST …/service-accounts/{id}/keys` — the secret is returned once. */
+    createKey(id: string, opts?: {
+        org?: string;
+        signal?: AbortSignal;
+    }): Promise<ServiceAccountKey>;
+    /** `POST …/service-accounts/{id}/keys/{key}/rotate`. */
+    rotateKey(id: string, keyId: string, opts?: {
+        org?: string;
+        signal?: AbortSignal;
+    }): Promise<ServiceAccountKey>;
+    /** `DELETE …/service-accounts/{id}/keys/{key}`. */
+    deleteKey(id: string, keyId: string, opts?: {
+        org?: string;
+        signal?: AbortSignal;
+    }): Promise<void>;
+}
+
+/**
+ * The {@link CAVS} client — the entry point of the SDK.
+ *
+ * ```ts
+ * import { CAVS } from "@cavsnode/cavs-sdk";
+ * const client = CAVS.fromEnv();
+ * const art = await client.artifacts.upload({ path: "./model", project: "vision-models",
+ *   name: "resnet50", kind: "model", version: "1.4.0" });
+ * await client.artifacts.download(art.reference, { dest: "./out" });
+ * ```
+ */
+
+/** The default control-plane base URL. */
+declare const DEFAULT_API = "https://api.cavs.dev";
+interface CAVSOptions {
+    /** Auth token. Falls back to `$CAVS_TOKEN`. */
+    token?: string;
+    /** Base URL of the CAVS Hub. Falls back to `$CAVS_API` then {@link DEFAULT_API}. */
+    api?: string;
+    /**
+     * Default organization slug for org-scoped calls. Falls back to `$CAVS_ORG`.
+     * Repository/upload/download calls do not require it (they key on the repo).
+     */
+    org?: string;
+    /** Injectable `fetch` — makes the client trivial to mock in tests. */
+    fetch?: FetchLike;
+    /** Override the `X-CAVS-Integration` header (default `javascript-sdk`). */
+    integration?: string;
+    /** Override the `X-CAVS-Integration-Version` header. */
+    integrationVersion?: string;
+    /** Optional `X-CAVS-Run-ID` correlation id. */
+    runId?: string;
+    /** Per-attempt request timeout in ms (default 30000). */
+    timeoutMs?: number;
+    /** Max retries on 429/5xx/network (default 4). */
+    maxRetries?: number;
+    /** Called when the server sends `X-CAVS-Deprecation`. */
+    onDeprecation?: (message: string) => void;
+    /** Internal/testing knobs forwarded to the transport. */
+    retryBaseMs?: number;
+    sleepImpl?: (ms: number) => Promise<void>;
+}
+/** Context handed to each resource module. */
+interface ClientContext {
+    http: HttpClient;
+    defaultOrg?: string;
+}
+declare class CAVS {
+    readonly http: HttpClient;
+    private readonly defaultOrg?;
+    readonly artifacts: ArtifactsResource;
+    readonly snapshots: SnapshotsResource;
+    readonly releases: ReleasesResource;
+    readonly runs: RunsResource;
+    readonly lineage: LineageResource;
+    readonly usage: UsageResource;
+    readonly serviceAccounts: ServiceAccountsResource;
+    constructor(options?: CAVSOptions);
+    /** Construct a client from the environment (`CAVS_TOKEN`, `CAVS_API`, `CAVS_ORG`). */
+    static fromEnv(options?: CAVSOptions): CAVS;
+    /** Resolve the org to use for org-scoped calls. */
+    resolveOrg(explicit?: string): string;
+    /** `GET /api/v1/users/me` — the authenticated identity. */
+    me(signal?: AbortSignal): Promise<Me>;
+    /** `GET /api/v1/search?q=` — cross-org search. */
+    search(q: string, signal?: AbortSignal): Promise<unknown>;
+    /** `GET /api/v1/resolve?uri=` — resolve a `cavs://` reference to concrete objects. */
+    resolve(reference: string, signal?: AbortSignal): Promise<unknown>;
+    /** `GET /api/v1/organizations/{org}/repositories`. */
+    listRepositories(org?: string, signal?: AbortSignal): Promise<unknown>;
+}
+
+/**
+ * Typed error hierarchy for the CAVS SDK.
+ *
+ * The server returns errors using the envelope described in CONTRACT.md §8:
+ *
+ *   { "error": { "code": "quota_exceeded", "message": "human readable" } }
+ *
+ * {@link toCAVSError} maps an HTTP status + envelope to the correct subclass.
+ * All errors extend {@link CAVSError}. Tokens and presigned URLs are NEVER
+ * included in error messages (CONTRACT.md §2).
+ */
+interface CAVSErrorOptions {
+    /** Machine-readable error code from the server envelope. */
+    code?: string;
+    /** HTTP status code, when the error originated from a response. */
+    status?: number;
+    /** Server-supplied request id (from `X-Request-Id`/`X-CAVS-Request-Id`), if any. */
+    requestId?: string;
+    /** Underlying cause (e.g. a network error). */
+    cause?: unknown;
+    /** Retry-After hint in milliseconds, when the server supplied one. */
+    retryAfterMs?: number;
+}
+/** Base class for every error thrown by the SDK. */
+declare class CAVSError extends Error {
+    readonly code?: string;
+    readonly status?: number;
+    readonly requestId?: string;
+    readonly retryAfterMs?: number;
+    constructor(message: string, options?: CAVSErrorOptions);
+}
+/** 401 — the token is missing, malformed or rejected. */
+declare class AuthenticationError extends CAVSError {
+}
+/** 403 — the token is valid but not permitted to perform the action. */
+declare class AuthorizationError extends CAVSError {
+}
+/** 404 — the requested resource does not exist. */
+declare class NotFoundError extends CAVSError {
+}
+/** 409 — the request conflicts with the current state of the resource. */
+declare class ConflictError extends CAVSError {
+}
+/** 429 — rate limited. Honour {@link CAVSError.retryAfterMs}. */
+declare class RateLimitError extends CAVSError {
+}
+/** 413 / 402 — a storage/billing quota has been exceeded. */
+declare class QuotaExceededError extends CAVSError {
+}
+/** A downloaded object's sha256 did not match its oid. */
+declare class ChecksumError extends CAVSError {
+}
+/** The upload data-plane transfer failed. */
+declare class UploadError extends CAVSError {
+}
+/** The download data-plane transfer failed. */
+declare class DownloadError extends CAVSError {
+}
+/** 5xx / network / timeout — a transient failure that is retried. */
+declare class TemporaryServiceError extends CAVSError {
+}
+
+/**
+ * `cavs://` URI parsing and formatting (CONTRACT.md §9).
+ *
+ *   cavs://{org}/{project}/{kind}/{name}:{version}            logical (mutable)
+ *   cavs://{org}/{project}/{kind}/{name}@sha256:{oid}         immutable
+ *
+ * Behaviour is pinned by spec/contract/uri-vectors.json — every valid vector
+ * must parse to its `parsed` object and reformat to its `canonical` string, and
+ * every invalid vector must throw.
+ */
+
+/** A parsed `cavs://` URI. Exactly one of {@link version} / {@link oid} is set. */
+interface ParsedURI {
+    org: string;
+    project: string;
+    kind: string;
+    name: string;
+    /** Logical version tag, or `null` for immutable references. */
+    version: string | null;
+    /** 64-char lowercase hex sha256, or `null` for logical references. */
+    oid: string | null;
+    /** `true` when the reference is pinned to an oid. */
+    immutable: boolean;
+}
+/** Raised when a string is not a valid `cavs://` URI. */
+declare class InvalidURIError extends CAVSError {
+}
+/**
+ * Parse a `cavs://` URI into its components.
+ *
+ * @throws {InvalidURIError} when the URI is malformed.
+ */
+declare function parse(uri: string): ParsedURI;
+/** Format a {@link ParsedURI} (or the equivalent fields) back to a canonical string. */
+declare function format(parsed: {
+    org: string;
+    project: string;
+    kind: string;
+    name: string;
+    version?: string | null;
+    oid?: string | null;
+}): string;
+
+type uri_InvalidURIError = InvalidURIError;
+declare const uri_InvalidURIError: typeof InvalidURIError;
+type uri_ParsedURI = ParsedURI;
+declare const uri_format: typeof format;
+declare const uri_parse: typeof parse;
+declare namespace uri {
+  export { uri_InvalidURIError as InvalidURIError, type uri_ParsedURI as ParsedURI, uri_format as format, uri_parse as parse };
+}
+
+/**
+ * Streaming data-plane primitives (CONTRACT.md §5, §6, §P6).
+ *
+ * Everything here streams: files are hashed and transferred chunk-by-chunk and
+ * are NEVER read whole into memory. Downloads are verified (sha256 === oid) and
+ * atomically renamed; temp files are removed on failure; path traversal is
+ * guarded.
+ */
+
+interface HashOptions {
+    signal?: AbortSignal;
+    onProgress?: (loaded: number) => void;
+    /** Chunk size for the read stream; the resulting oid is independent of this. */
+    highWaterMark?: number;
+}
+/**
+ * Compute the streaming sha256 ("oid") and byte size of a file. The whole file
+ * is never buffered in memory.
+ */
+declare function sha256File(filePath: string, opts?: HashOptions): Promise<{
+    oid: string;
+    size: number;
+}>;
+
+export { type AddEdgeOptions, type Artifact, type ArtifactFile, type ArtifactVersion, AuthenticationError, AuthorizationError, CAVS, CAVSError, type CAVSErrorOptions, type CAVSOptions, ChecksumError, type ClientContext, ConflictError, type CreateRunOptions, type CreateServiceAccountOptions, type CreateSnapshotOptions, DEFAULT_API, DownloadError, type DownloadOptions, type DownloadResult, type DownloadedFile, InvalidURIError, type LineageEdge, type LineageGraph, type Me, NotFoundError, type Org, type ParsedURI, type ProgressCallback, type ProgressEvent, QuotaExceededError, RateLimitError, type Release, type Repo, type Run, type RunArtifact, type ServiceAccount, type ServiceAccountKey, type Snapshot, TemporaryServiceError, type UpdateRunOptions, UploadError, type UploadOptions, type UploadResult, type UploadedFile, type Usage, VERSION, sha256File, uri };