# TypeScript SDK

`strovio-sdk` is a typed client for the Strovio REST API. It runs in Node.js 18 or later (it uses `fetch` and `Buffer`) and ships CommonJS, ES module and type definitions.

## Install

Check that it is published and see the latest version:

```bash
npm view strovio-sdk version
```

If that prints `404 Not Found`, the SDK is not published yet; use the [REST API](https://strovio.xyz/docs/api). Otherwise:

```bash
npm install strovio-sdk
```

## Configure

```ts
import { StrovioClient } from "strovio-sdk";

const strovio = new StrovioClient();
```

With no options the client reads `STROVIO_API_KEY` and `STROVIO_API_URL` from the environment. `STROVIO_API_URL` defaults to `https://strovio.xyz`. You can pass them instead:

```ts
const strovio = new StrovioClient({
  apiKey: process.env.MY_STROVIO_KEY,
  apiUrl: "https://strovio.xyz",
  timeoutMs: 30000,
});
```

`apiUrl` must use `https://` unless it points at `localhost`. `timeoutMs` is per request, from 1 to 120000, default 30000. A missing key throws a `StrovioError` with status 401 that says where to create one.

## Upload

```ts
import { readFile } from "node:fs/promises";

const file = await strovio.upload("reports/q1.pdf", await readFile("q1.pdf"), {
  contentType: "application/pdf",
  access: "private",
});
console.log(file.key, file.url);
```

- `key` is the path to store under. No leading `/`, no `..`, no empty segments.
- `body` is a `Buffer`, `Uint8Array`, `Blob` or `ReadableStream`, up to 50 MiB. The SDK reads the whole body into memory first. For larger files use the script in [Upload large files](https://strovio.xyz/docs/large-uploads).
- `access` is `"public"` or `"private"` (default `"private"`). `contentType` defaults to `application/octet-stream`.
- Bodies over 1 MiB are sent as a multipart upload automatically.
- Returns `{ key, name, size, contentType, access, url, createdAt }`. `url` is the permanent public URL for public files and `null` for private files.

`UploadOptions` also accepts `idempotencyKey`, `metadata` and `expectedOwnerId`. They are sent as headers but the API does not use them today. Retrying an upload to the same key and access replaces the same file, so retries do not create duplicates.

## List

```ts
const { objects, count } = await strovio.list({ prefix: "reports/", limit: 50 });
```

`prefix` matches keys that contain the text anywhere, so `reports/` also matches `old/reports/`. `limit` is 1 to 100 in the SDK. Files come newest first.

## Get a download URL

```ts
const detail = await strovio.get("reports/q1.pdf");
console.log(detail.url, detail.expiresIn);
```

Private files return a signed URL valid for 3600 seconds (`expiresIn: 3600`). Public files return their permanent URL (`expiresIn: null`).

## Check and delete

```ts
const { exists, size } = await strovio.exists("reports/q1.pdf");
await strovio.delete("reports/q1.pdf");
```

`exists` sends a `HEAD` request and returns `{ exists: false }` for a missing file. `delete` returns `{ ok: true, key }` and is permanent.

## Errors

Every failure throws `StrovioError`:

```ts
import { StrovioError } from "strovio-sdk";

try {
  await strovio.get("missing.txt");
} catch (err) {
  if (err instanceof StrovioError) {
    console.log(err.statusCode, err.code, err.docUrl, err.message);
  }
}
```

`code` and `docUrl` come from the API; see [Errors](https://strovio.xyz/docs/errors). Input checks in the SDK throw status 400 before any request, and timeouts throw status 408.

## Without the SDK

Until the package is published, the same calls work with `fetch` in Node.js 18+:

```js
import { readFile } from "node:fs/promises";

const api = "https://strovio.xyz/api/v1";
const headers = { Authorization: `Bearer ${process.env.STROVIO_API_KEY}` };

const put = await fetch(`${api}/files/reports/q1.pdf`, {
  method: "PUT",
  headers: { ...headers, "Content-Type": "application/pdf", "X-Access": "private" },
  body: await readFile("q1.pdf"),
});
if (!put.ok) throw new Error(JSON.stringify(await put.json()));

const file = await (await fetch(`${api}/files/reports/q1.pdf`, { headers })).json();
console.log(file.url);
```

Error bodies are `{ error, code, doc_url }`.

## Exports

`StrovioClient`, `StrovioError`, `DEFAULT_API_URL`, and the types `StrovioClientOptions`, `StrovioFile`, `StrovioFileDetail`, `StrovioListResult`, `StrovioUploadResult`, `StrovioDeleteResult`, `StrovioHeadResult`, `UploadOptions`, `ListOptions` and `AccessLevel`.

---

Source: https://strovio.xyz/docs/sdk
All docs for agents: https://strovio.xyz/llms.txt