@cavsnode/cavs-sdk 0.1.0

package/README.md

@@ -0,0 +1,85 @@
+# @cavsnode/cavs-sdk
+
+Official **TypeScript / JavaScript SDK** for [CAVS Hub](https://github.com/orelvis15/cavs-hub) — the
+deduplicating, content-addressed artifact store for AI, CI/CD and game pipelines.
+
+It talks to the same canonical `/api/v1` API the CLI uses (see
+[`../CONTRACT.md`](../CONTRACT.md)). Uploads and downloads **stream** — files are
+never read whole into memory — and every download is verified (`sha256 === oid`).
+
+- Node **18+** (uses the global `fetch`, Web Streams and `node:crypto`).
+- Ships ESM + CJS with type declarations.
+
+## Install
+
+```bash
+npm install @cavsnode/cavs-sdk
+```
+
+## Authentication
+
+```bash
+export CAVS_TOKEN=cavs_sk_...          # a service-account key from the dashboard
+export CAVS_API=https://api.cavs.dev   # or your self-hosted Hub
+```
+
+Tokens are never printed in logs or errors. See [`../CONTRACT.md`](../CONTRACT.md) §2.
+
+## Quick start
+
+```ts
+import { CAVS } from "@cavsnode/cavs-sdk";
+
+const client = CAVS.fromEnv();
+
+const artifact = await client.artifacts.upload({
+  path: "./model",
+  project: "vision-models",
+  name: "resnet50",
+  kind: "model",
+  version: "1.4.0",
+  metadata: { framework: "pytorch", accuracy: 0.942 },
+  onProgress: (e) => process.stdout.write(`\r${e.phase} ${e.path} ${e.loaded}/${e.total}`),
+});
+
+console.log(artifact.reference);          // cavs://…/model/resnet50:1.4.0
+console.log(artifact.deduplicationRatio); // e.g. 0.6
+
+await client.artifacts.download(artifact.reference, { dest: "./restored" });
+```
+
+## What's included
+
+- `client.artifacts` — `upload`, `download`, `get`, `versions`, `list`
+- `client.runs` — create/update pipeline runs and record lineage
+- `client.lineage`, `client.snapshots`, `client.releases`, `client.usage`
+- `client.serviceAccounts` — manage service accounts and API keys
+- Typed errors: `CAVSError`, `AuthenticationError`, `AuthorizationError`,
+  `NotFoundError`, `ConflictError`, `RateLimitError`, `QuotaExceededError`,
+  `ChecksumError`, `UploadError`, `DownloadError`, `TemporaryServiceError`
+- `uri.parse` / `uri.format` for `cavs://` references
+
+## Retries, timeouts and cancellation
+
+Requests retry up to 4 times on `429`/`5xx`/network errors with exponential
+backoff, honouring `Retry-After`. Pass an `AbortSignal` to cancel any call:
+
+```ts
+const ac = new AbortController();
+const p = client.artifacts.upload({ /* … */, signal: ac.signal });
+ac.abort();
+```
+
+## Development
+
+```bash
+npm ci
+npm run lint && npm run typecheck && npm test   # vitest, coverage gate ≥90%
+npm run build                                    # tsup → dist/ (ESM + CJS + d.ts)
+```
+
+See [`../CONTRIBUTING.md`](../CONTRIBUTING.md) and [`../docs/typescript.md`](../docs/typescript.md).
+
+## License
+
+Apache 2.0 — see [`../LICENSE`](../LICENSE).