Typescript SDK

A TypeScript SDK for interacting with Koneksi API services. This SDK provides a clean and intuitive interface for managing directories, files, and other resources in the Koneksi platform.

Link: https://www.npmjs.com/package/koneksi-ts-sdk

Features

🗂️ Directory Management - Create, read, update, delete, rename, and move directories
📁 File Operations - Upload, download, read, update, delete, rename, move files
🔐 File Access Control - Set public, private, password, or email-based access
🔗 Temporary Links - Generate temporary access tokens and preview links
🏥 Health Monitoring - Check API service health status
👥 Peer Management - Fetch available peers
🔒 Encryption Support - Upload and download encrypted files with passphrases
🌐 Multi-Environment Support - Local, staging, UAT, and production environments
📝 Full TypeScript Support - Complete type definitions and IntelliSense

Installation

npm install koneksi-ts-sdk

Quick Start

import KoneksiSDK from "koneksi-ts-sdk";

// Initialize the SDK
const sdk = new KoneksiSDK({
  environment: "uat", // "local", "staging", "uat", "production" // optional, defaults to uat
  client_id: "your_client_id",
  client_secret: "your_client_secret",
});

// Check API health
const health = await sdk.health.check();

// Create a directory
const directory = await sdk.directory.create({
  name: "My Documents",
  directory_id: "parent_directory_id", // optional
});

// Upload a file
const uploadResult = await sdk.file.upload({
  file: "important_file.pdf", // File object, Buffer, or string path
  directory_id: directory.id,
  passphrase: "MySecret123!", // optional for encryption
});

// Download a file
const fileBuffer = await sdk.file.download({
  fileId: uploadResult.file_id,
  passphrase: "MySecret123!", // required for encrypted files
});

Configuration

The SDK supports multiple environments with different API endpoints:

const sdk = new KoneksiSDK({
  environment: "uat", // "local", "staging", "uat", "production". Optional, defaults to uat
  client_id: "your_client_id",
  client_secret: "your_client_secret",
});

API Reference

Directory Operations

The sdk.directory object provides methods for managing directories.

Create Directory

Creates a new directory in the specified parent directory.

const directory = await sdk.directory.create({
  name: "Directory Name",
  directory_id: "parent_directory_id", // optional, defaults to root
});

Read Directory

Retrieves directory details including files and subdirectories.

const directoryData = await sdk.directory.read("directory_id");

// Returns: DirectoryReadResponse
// {
//   directory: Directory,
//   files: FileInDirectory[],
//   subdirectories: Subdirectory[]
// }

Update Directory

Updates directory properties (name and/or parent directory).

const message = await sdk.directory.update("directory_id", {
  name: "New Name",
  directory_id: "new_parent_directory_id", // optional
});

// Returns: Success message string

Delete Directory

Deletes a directory and all its contents.

const message = await sdk.directory.delete("directory_id");

// Returns: Success message string

Rename Directory

Renames a directory with a new name.

const message = await sdk.directory.rename({
  directoryId: "directory_id",
  name: "New Directory Name",
});

// Returns: Success message string

Move Directory

Moves a directory to a new parent directory.

const message = await sdk.directory.move({
  directoryId: "directory_id",
  parentDirectoryId: "new_parent_directory_id",
});

// Returns: Success message string

File Operations

The sdk.file object provides comprehensive file management capabilities.

Upload File

Uploads a file to a directory with optional encryption.

// Browser environment - using File object
const uploadResult = await sdk.file.upload({
  file: fileInput.files[0], // File object
  directory_id: "target_directory_id", // optional
  passphrase: "MySecret123!", // optional for encryption
});

// Node.js environment - using file path
const uploadResult = await sdk.file.upload({
  file: "/path/to/file.txt", // string file path
  directory_id: "target_directory_id",
  passphrase: "MySecret123!", // required for encryption in Node.js
});

// Using Buffer
const uploadResult = await sdk.file.upload({
  file: Buffer.from("file content"),
  directory_id: "target_directory_id",
});

// Returns: UploadFileResponse
// {
//   content_type: string,
//   directory_id: string,
//   file_id: string,
//   hash: string,
//   name: string,
//   size: number
// }

Read File

Retrieves file details and metadata.

const file = await sdk.file.read({
  fileId: "file_id",
  includeChunks: false, // optional, default: false
});

// Returns: FileData
// {
// id: string;
//  content_type: string;
//  directory_id: string;
//  hash: string;
//  name: string;
//  size: number;
//  is_shared: boolean;
//  is_encrypted: boolean;
//  access: string;
//  recipients: string[];
//  created_at: string;
//  updated_at: string;
// }

Update File

Updates file properties.

const message = await sdk.file.update("file_id", {
  name: "New File Name",
  directory_id: "new_directory_id", // optional
});

// Returns: Success message string

Delete File

Deletes a file permanently.

const message = await sdk.file.delete("file_id");

// Returns: Success message string

Download File (Authenticated)

Downloads a file using authenticated access (for private or encrypted files).

const fileBuffer = await sdk.file.download({
  fileId: "file_id",
  passphrase: "MySecret123!", // required for encrypted files
});

// Returns: Buffer containing file content

Rename File

Renames a file with a new name.

const message = await sdk.file.rename({
  fileId: "file_id",
  name: "new_file_name.txt",
});

// Returns: Success message string

Move File

Moves a file to a different directory.

const message = await sdk.file.move({
  fileId: "file_id",
  directory_id: "target_directory_id",
});

// Returns: Success message string

Set File Access

Configures file access permissions.

// Set to public access
await sdk.file.setAccess({
  fileId: "file_id",
  access: "public",
});

// Set to private access
await sdk.file.setAccess({
  fileId: "file_id",
  access: "private",
});

// Set password protection
await sdk.file.setAccess({
  fileId: "file_id",
  access: "password",
  value: "1234567890",
});

// Set email-based access
await sdk.file.setAccess({
  fileId: "file_id",
  access: "email",
  value: ["user1@example.com", "user2@example.com"], // existing Koneksi accounts
});

// Returns: Success message string

Generate Temporary Token

Creates a temporary access token for a file.

const token = await sdk.file.generateTemporaryToken({
  fileId: "file_id",
  expiresIn: 3600, // optional, default: 24 hours (in seconds)
});

// Returns: GenerateTemporaryTokenResponse
// {
//   duration: "1h0m0s",
//   file_key: "file_1234567890_abc123..."
// }

Get Preview Link

Gets a permanent preview link for a file.

const preview = await sdk.file.getPreviewLink({
  fileId: "file_id",
});

// Returns: GetPreviewLinkResponse
// {
//   previewUrl: "https://app-staging.koneksi.co.kr/preview/file_1234567890"
// }

Create Temporary Link

Creates a temporary preview link with an expiration time.

const tempLink = await sdk.file.createTemporaryLink({
  fileId: "file_id",
  expiresIn: 3600, // optional, default: 24 hours (in seconds)
});

// Returns: CreateTemporaryLinkResponse
// {
//   temporaryPreviewUrl: "https://app-staging.koneksi.co.kr/preview/file_1234567890?token=abc123...",
//   duration: "1h0m0s",
//   file_key: "file_1234567890_abc123..."
// }

Read File Access (Public)

Gets file access information using the public endpoint.

const accessInfo = await sdk.file.publicRead({
  fileId: "file_id",
});

// Returns: ReadFileAccessResponse
// {
//   access: "public" | "private" | "password" | "email",
//   is_encrypted: boolean,
//   id: string,
//   size: number
// }

Download File (Public)

Downloads a file using public access methods (tokens, passwords, etc.).

// Using temporary token
const fileBuffer = await sdk.file.publicDownload({
  fileId: "file_id",
  temporaryToken: "token123",
  passphrase: "MySecret123!", // optional for encrypted files
});

// Using password protection
const fileBuffer = await sdk.file.publicDownload({
  fileId: "file_id",
  shared: {
    access: "password",
    value: "Password123!",
  },
  passphrase: "MySecret123!", // optional for encrypted files
});

// Returns: Buffer containing file content

Health Operations

The sdk.health object provides API health monitoring.

Check Health

Checks the health status of the API service.

const health = await sdk.health.check();

// Returns: HealthResponse
// {
//   data: any,
//   message: string,
//   meta: any,
//   status: string
// }

Peers Operations

The sdk.peers object provides peer management capabilities.

Fetch Peers

Retrieves available peers for the authenticated client.

const peers = await sdk.peers.read();

Complete Examples

File Management Workflow

import KoneksiSDK from "koneksi-ts-sdk";

const sdk = new KoneksiSDK({
  environment: "uat",
  client_id: "your_client_id",
  client_secret: "your_client_secret",
});

async function completeFileWorkflow() {
  try {
    // 1. Check API health
    const health = await sdk.health.check();
    console.log("API Health:", health.status);

    // 2. Create a directory structure
    const documentsDir = await sdk.directory.create({
      name: "Documents",
    });

    const projectsDir = await sdk.directory.create({
      name: "Projects",
      directory_id: documentsDir.id,
    });

    // 3. Upload an encrypted file
    const uploadResult = await sdk.file.upload({
      file: "important_file.pdf,
      directory_id: projectsDir.id,
      passphrase: "MySecret123!",
    });

    // 4. Set file access to password-protected
    await sdk.file.setAccess({
      fileId: uploadResult.file_id,
      access: "password",
      value: "FilePassword123!",
    });

    // 5. Create a temporary preview link
    const tempLink = await sdk.file.createTemporaryLink({
      fileId: uploadResult.file_id,
      expiresIn: 3600, // 1 hour
    });

    // 6. Read directory contents
    const directoryData = await sdk.directory.read(documentsDir.id);
    console.log("Files:", directoryData.files);
    console.log("Subdirectories:", directoryData.subdirectories);

    // 7. Download the file
    const fileBuffer = await sdk.file.download({
      fileId: uploadResult.file_id,
      passphrase: "MySecret123!",
    });

    // 8. Move file to different directory
    await sdk.file.move({
      fileId: uploadResult.file_id,
      directory_id: documentsDir.id,
    });

    // 9. Rename the file
    await sdk.file.rename({
      fileId: uploadResult.file_id,
      name: "Updated File Name.txt",
    });

    // 10. Clean up
    await sdk.file.delete(uploadResult.file_id);
    await sdk.directory.delete(projectsDir.id);
    await sdk.directory.delete(documentsDir.id);

    console.log("Workflow completed successfully!");
  } catch (error) {
    console.error("Error:", error.message);
  }
}

Peer Management

async function managePeers() {
  try {
    // Fetch available peers
    const peers = await sdk.peers.read();

    console.log("Available peers:");
    peers.forEach((peer) => {
      console.log(
        `- ${peer.name} (${peer.status}) - Created: ${peer.created_at}`
      );
    });
  } catch (error) {
    console.error("Failed to fetch peers:", error.message);
  }
}

Health Monitoring

async function monitorHealth() {
  try {
    const health = await sdk.health.check();

    if (health.status === "success") {
      console.log("✅ API is healthy:", health.message);
    } else {
      console.log("❌ API health check failed:", health.message);
    }
  } catch (error) {
    console.error("Health check error:", error.message);
  }
}

Error Handling

The SDK provides comprehensive error handling with descriptive error messages:

try {
  const directory = await sdk.directory.create({
    name: "Test Directory",
  });
} catch (error) {
  console.error("Failed to create directory:", error.message);
  // Error messages are descriptive and actionable
}

TypeScript Support

The SDK is built with TypeScript and provides full type safety:

import {
  Directory,
  FileData,
  UploadFileResponse,
  DirectoryReadResponse,
  CreateDirectoryRequest,
  Peer,
  HealthResponse,
} from "koneksi-ts-sdk";

// All parameters and return types are fully typed
const createParams: CreateDirectoryRequest = {
  name: "My Directory",
};

const directory: Directory = await sdk.directory.create(createParams);
const fileData: FileData = await sdk.file.read({ fileId: "file_id" });
const peers: Peer[] = await sdk.peers.read();
const health: HealthResponse = await sdk.health.check();

Development

Building the SDK

npm run build

Running Tests

npm test

Linting

npm run lint

Formatting

npm run format

License

MIT

PreviousQuick Start NextAPIs

Last updated 11 days ago