Dilnaka TypeScript SDK

Install the published Dilnaka package from npm. The package name matches the Python SDK package name, so the constructor import stays consistent across languages.

Package: npmjs.com/package/dilnaka

npm install dilnaka

Minimum runtime: Node.js 18+. If you run in a custom environment, pass a compatible fetch implementation in the constructor options.

The SDK only needs your API key in .env. It is built specifically for Dilnaka Storage.

DILNAKA_API_KEY=dlk_dev_your_api_key_here

DILNAKA_TIMEOUT=60

Optional: set DILNAKA_TIMEOUT if you want a custom request timeout.

Core flow

Basic upload

Instantiate the client with defaults and upload a local file path with one async method call.

import { Dilnaka } from "dilnaka";

const client = new Dilnaka();

const uploaded = await client.upload("./test-upload.txt");

console.log(uploaded.id);
console.log(uploaded.key);
console.log(uploaded.status);

Alternate setup

Explicit configuration

Pass constructor options directly when you want to avoid environment files, change the timeout, or inject a custom fetch implementation for tests or another runtime.

import { Dilnaka } from "dilnaka";

const client = new Dilnaka({
  apiKey: "dlk_dev_your_api_key_here",
  timeout: 60,
  fetch,
});

const uploaded = await client.upload("./avatar.png", {
  folder: "avatars",
  metadata: { source: "profile-settings" },
});

console.log(uploaded);

Read access

Request file access URLs

Use getFileAccessUrl(fileId, expiresIn?) when your app needs a temporary download or preview URL.

import { Dilnaka } from "dilnaka";

const client = new Dilnaka();

const access = await client.getFileAccessUrl("file_123", 600);

console.log(access.fileId);
console.log(access.url);
console.log(access.expiresIn);
console.log(access.isTemporary);

If you omit expiresIn, the SDK requests the default access URL returned by your backend. The method rejects values less than or equal to zero.

API surface

Available methods

const client = new Dilnaka({
  apiKey?: string;
  timeout?: number;
  envFile?: string;
  fetch?: typeof fetch;
});

await client.upload(filePath, options?);
await client.createPresignedUpload(options);
await client.completeUpload(fileId);
await client.listFiles();
await client.getFile(fileId);
await client.getFileAccessUrl(fileId, expiresIn?);
await client.deleteFile(fileId);

Backend contract

Expected backend endpoints

The TypeScript SDK uses the same Caspian endpoints as the Python SDK.

POST /v1/uploads/presign
POST /v1/uploads/complete
GET  /v1/files
GET  /v1/files/{file_id}
GET  /v1/files/{file_id}/access-url?expiresIn=1200
DELETE /v1/files/{file_id}

When you pass expiresIn to getFileAccessUrl, the SDK appends it as a query parameter on the access URL endpoint.

API payloads

Presign and complete response shapes

{
  "fileId": "clx_file_id",
  "fileKey": "uploads/2026/05/clx_file_id-test.txt",
  "uploadUrl": "https://s3-presigned-url",
  "expiresIn": 300,
  "method": "PUT",
  "headers": {
    "Content-Type": "text/plain"
  }
}

{
  "fileId": "clx_file_id",
  "status": "uploaded",
  "key": "uploads/2026/05/clx_file_id-test.txt",
  "originalName": "test.txt",
  "contentType": "text/plain",
  "size": 94,
  "publicUrl": null,
  "etag": "\"3b5d5c3712955042212316173ccf37be\""
}

{
  "fileId": "clx_file_id",
  "url": "https://s3-presigned-url",
  "expiresIn": 1200,
  "isTemporary": true
}

Examples

Common usage patterns

import { Dilnaka } from "dilnaka";

const client = new Dilnaka();

const access = await client.getFileAccessUrl(
  "maext0cfjsquw2mu9o597fb9",
  1200,
);

console.log(access.url);
console.log(access.expiresIn);

import { Dilnaka } from "dilnaka";

const client = new Dilnaka();

const fileId = "maext0cfjsquw2mu9o597fb9";
const result = await client.deleteFile(fileId);

console.log(result);

import { Dilnaka } from "dilnaka";

const client = new Dilnaka();

const uploaded = await client.upload("./test-upload.txt", {
  folder: "uploads",
});

console.log("Uploaded file:");
console.log("  id: " + uploaded.id);
console.log("  key: " + uploaded.key);
console.log("  status: " + uploaded.status);
console.log("  size: " + uploaded.size);
console.log("  contentType: " + uploaded.contentType);

import { Dilnaka } from "dilnaka";

const client = new Dilnaka();

for (const file of await client.listFiles()) {
  console.log(file.id + " | " + file.status + " | " + file.key);
}