npm package: @kamimind/storage
Description: TypeScript SDK for Kamimind Storage Service
Author: Kamimind Team
Latest version: 0.1.5

# Kamimind Storage SDK for TypeScript

[![npm version](https://badge.fury.io/js/@kamimind%2Fstorage.svg)](https://www.npmjs.com/package/@kamimind/storage)
[![License](https://img.shields.io/github/license/kamimind/storage-sdk)](LICENSE)

Official TypeScript SDK for Kamimind Storage Service.

## Installation

Install from [npm](https://www.npmjs.com/package/@kamimind/storage):

```bash
# Using bun (recommended)
bun add @kamimind/storage

# Using npm
npm install @kamimind/storage

# Using yarn
yarn add @kamimind/storage

# Using pnpm
pnpm add @kamimind/storage
```

## Quick Start

```typescript
import { StorageClient } from '@kamimind/storage';

// Initialize client
const client = new StorageClient({
  baseUrl: 'https://api.kamimind.ai',
  accessToken: 'your-jwt-token',
});

// Upload a file
const session = await client.uploadFile(file, { isPublic: true });
console.log(`Uploaded: ${session.sessionId}`);

// Get download URL
const download = await client.getDownloadUrl(session.sessionId);
console.log(`Download URL: ${download.downloadUrl}`);

// Make file public
const publicInfo = await client.makePublic(session.sessionId);
console.log(`Public URL: ${publicInfo.publicUrl}`);
```

## Features

### File Upload

```typescript
// Upload a File object (browser)
const file = document.querySelector('input[type="file"]').files[0];
const session = await client.uploadFile(file);

// Upload a Blob
const blob = new Blob(['Hello, World!'], { type: 'text/plain' });
const session = await client.uploadFile(blob, { filename: 'hello.txt' });

// Upload with progress callback
const session = await client.uploadFile(file, {
  onProgress: (progress) => {
    console.log(`Uploaded: ${progress.percentage.toFixed(1)}%`);
  },
});

// Upload with metadata
const session = await client.uploadFile(file, {
  metadata: { category: 'reports', year: 2024 },
  isPublic: true,
});
```

### File Download

```typescript
// Get download URL
const downloadInfo = await client.getDownloadUrl(sessionId);
console.log(downloadInfo.downloadUrl);

// Download as Blob (browser)
const blob = await client.downloadFile(sessionId);

// Download to file (Node.js)
const path = await client.downloadFile(sessionId, {
  destination: './downloads/file.pdf',
});
```

### Public Sharing

```typescript
// Make file public
const publicInfo = await client.makePublic(sessionId);
console.log(`Public URL: ${publicInfo.publicUrl}`);

// Toggle public access
await client.togglePublicAccess(sessionId, false);

// Get public URL by shortcut
const publicUrl = client.getPublicUrl('abc12345');
```

### Session Management

```typescript
// Get upload status
const status = await client.getUploadStatus(sessionId);
console.log(`Status: ${status.status}`);

// Abort upload
await client.abortUpload(sessionId);
```

### Cancellation

```typescript
// Cancel an upload
const controller = new AbortController();

const uploadPromise = client.uploadFile(file, {
  signal: controller.signal,
});

// Cancel after 5 seconds
setTimeout(() => controller.abort(), 5000);

try {
  await uploadPromise;
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Upload cancelled');
  }
}
```

## Configuration

```typescript
const client = new StorageClient({
  baseUrl: 'https://h2-storage.kamimind.ai',
  accessToken: 'your-jwt-token',
  timeout: 60000, // Request timeout in milliseconds
  maxRetries: 3, // Max retry attempts
  multipartThreshold: 100 * 1024 * 1024, // 100MB threshold for multipart
  partSize: 5 * 1024 * 1024, // 5MB part size
});
```

## Error Handling

```typescript
import {
  StorageError,
  AuthenticationError,
  NotFoundError,
  UploadError,
  QuotaExceededError,
} from '@kamimind/storage';

try {
  const session = await client.uploadFile(file);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.log('Invalid or expired token');
  } else if (error instanceof QuotaExceededError) {
    console.log('Storage quota exceeded');
  } else if (error instanceof UploadError) {
    console.log(`Upload failed: ${error.message}`);
  } else if (error instanceof StorageError) {
    console.log(`Storage error: ${error.message}`);
  }
}
```

## Development

```bash
# Install dependencies
bun install

# Run tests
bun test

# Run tests with coverage
bun test --coverage

# Build
bun run build

# Lint
bun run lint

# Type check
bun run typecheck
```

## Running Examples

The SDK includes runnable example scripts that demonstrate various features:

```bash
# Set environment variables (optional)
export BASE_URL="http://localhost:8082"
export ACCESS_TOKEN="your-jwt-token"

# Run basic upload example
bun run example:basic

# Run multipart upload example
bun run example:multipart

# Run public sharing example
bun run example:public

# Run download example
bun run example:download
```

Or run them directly with Bun:

```bash
bun run examples/run-basic-upload.ts
bun run examples/run-multipart-upload.ts
bun run examples/run-public-sharing.ts
bun run examples/run-download.ts
```

## License

MIT License