npm package: @faulpeltz/kella-client
Description: Client library for Kella storage
Author: faulpeltz
Latest version: 0.1.4

# Kella Client

JS/TS client library for Kella

Features:

* Supports multiple servers (as in cluster) with automatic retry/failover
* Supports stream up/downloading

---

## Installation

``npm install @faulpeltz/kella-client``

## Usage

Here are some Typescript examples for the most common use cases:

```typescript
import { KellaClient } from "@faulpeltz/kella-client";
 
 // setup new client
 const kc = new KellaClient({
    clientToken: "<client access token>", // note: use an env var instead of hard coding
    serverUrls: ["https://example1.internal:6010/", "https://example2.internal:6020"],
    caCertificate: "./config/my-ca.crt", // alternatively use self-signed cert (or omit if already in cert chain)
    connectTimeout: 500, // client connection timeout
    keepAliveTimeout: 5000, // keepalive timeout for HTTP connection
    maxConnections: 10, // max connections per server
});

// get basic server info
const info = await kc.serverInfo();

// get namespaces in universe
const namespaces = await kc.namespaces("your-universe");

// upload a blob (returns blob metadata)
const uploadedInfo = await kc.upload({ 
    universe: "your-univ", // universe name - required
    namespace: "ns",  // namespace - required (namespaces are automatically created on the first blob upload)
    friendlyName: "blob1",  // friendly blob name (mus be a valid cross-platform filename)
    blobId: "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD",  // optional: custom blob id (32-alphanumeric), requires permission enabled universe config
    mimeType: "application/foobar", // optional: blob data mimetype, uses header by default
    encrypt: true, // optional if a storage key is configured, encrypts automatically, false turns off
    compress: true, // compresses with gzip for serving to (most) HTTP clients
    data, // data blob (Buffer, Stream, string)
});

// get namespace blob ids
const iteratableBlobIds = await kc.namespaceBlobIds("default", "myns");

// get namespace info (total count and uncompressed, not-deduplicated size)
const namespaceInfo = await kc.namespaceInfo("default", "myns");

// get blob metadata only
const blobInfo = await kc.blobInfo("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");

// download blob data
 const stream = await kc.download("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");
 const buffer = await kc.downloadBuffer("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");

// delete/undelete blob
await kc.deleteBlob("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");
await kc.undeleteBlob("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD");

// final delete blob (no undelete, still available on backup nodes until cleaned up)
await kc.deleteBlob("your-univ", "myns", "0a0B1c2dDe4F5g6h7i8j9lAmBnCoDpEqD", true);

// rename namespace (this can be slow and fail if servers are not replicating or very busy)
await kc.renameNamespace("your-univ", "myns", "newns");

// delete namespace (final deletes all blobs in a namespace)
await kc.deleteNamespace("your-univ", "myns");

// pin/unpin server (optional)
kc.selectServer(0); kc.deselectServer();

// handling errors
// will throw a KellaError in most cases
if (err instanceof KellaError && err.code === KellaErrorCode.NamespaceNotFound) { 
    ... 
}

```

## Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

## License

(c) faulpeltz
[MIT](https://choosealicense.com/licenses/mit/)