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:

npm view strovio-sdk version

If that prints 404 Not Found, the SDK is not published yet; use the REST API. Otherwise:

npm install strovio-sdk

Configure

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:

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

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.
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

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

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

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:

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. 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+:

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.