npm package: @lilaquadrat/storage-sdk
Description: SDK for accessing STUDIO storage/media API
Author: Mathias Schübel
Latest version: 0.1.13

# @lilaquadrat/storage-sdk

SDK for accessing STUDIO storage/media API with support for file uploads, downloads, and listing.

## Installation

```bash
npm install @lilaquadrat/storage-sdk
```

or

```bash
yarn add @lilaquadrat/storage-sdk
```

## Usage

```typescript
import StorageSDK from '@lilaquadrat/storage-sdk';

// Initialize the SDK
const storage = new StorageSDK(
  {
    api: 'https://media.lilaquadrat.studio',
    public: 'https://cdn.lilaquadrat.studio',
    secure: 'https://secure.lilaquadrat.studio',
  },
  5, // concurrency
  'info', // log level: 'debug' | 'info' | 'none'
  'your-access-token' // optional access token
);

// Upload a single file
await storage.upload(
  {
    filename: 'example.jpg',
    size: 1024,
    mimetype: 'image/jpeg',
    fullPath: '/path/to/example.jpg'
  },
  {
    app: 'media',
    company: 'your-company',
    project: 'your-project',
    thumbnails: true,
    overwrite: false
  }
);

// Upload multiple files
await storage.uploadMultiple(
  [
    { filename: 'file1.jpg', size: 1024, mimetype: 'image/jpeg', fullPath: '/path/to/file1.jpg' },
    { filename: 'file2.png', size: 2048, mimetype: 'image/png', fullPath: '/path/to/file2.png' }
  ],
  {
    app: 'media',
    company: 'your-company',
    project: 'your-project'
  }
);

// List files
const result = await storage.list(
  {
    app: 'media',
    company: 'your-company',
    project: 'your-project'
  },
  {
    tags: ['image'],
    prefix: 'uploads/',
    ignorePrefix: false
  }
);

// Download a file
const buffer = await storage.download({
  app: 'media',
  company: 'your-company',
  project: 'your-project',
  prefix: 'uploads',
  filename: 'example.jpg'
});

// Get access token
const token = await storage.getAccessToken('html', 'your-company', 'your-project');
```

## API

### Constructor

```typescript
new StorageSDK(endpoints: Endpoints, concurrency?: number, logLevel?: LogLevel, accessToken?: string)
```

- `endpoints`: Object containing API endpoints (api, public, secure)
- `concurrency`: Number of concurrent uploads (default: 5)
- `logLevel`: Logging level - 'debug', 'info', or 'none' (default: 'info')
- `accessToken`: Optional access token for authentication

### Methods

#### `upload(file: UploadFile, options: UploadOptions)`
Upload a single file to the storage.

#### `uploadMultiple(files: UploadFile[], options: UploadOptions)`
Upload multiple files with concurrency control.

#### `list(options: Options, params?: ListFilesParams)`
List files in the storage with optional filtering.

#### `download(blob: Storage): Promise<Buffer>`
Download a file from the storage.

#### `getAccessToken(app: string, company: string, project: string): Promise<string>`
Get an access token for downloading files from secured endpoints. Tokens are cached automatically.

## Types

### UploadFile
```typescript
type UploadFile = {
  filename: string;
  size: number;
  mimetype: string;
  fullPath: string;
};
```

### ListFilesParams
```typescript
type ListFilesParams = {
  tags?: string[];
  prefix?: string;
  ignorePrefix?: boolean;
};
```

### Endpoints
```typescript
type Endpoints = {
  api: string;
  public: string;
  secure: string;
};
```

## Development

### Building

```bash
yarn build
```

### Publishing to npm

1. Make sure you're logged in to npm:
   ```bash
   npm login
   ```

2. Update the version and generate changelog:
   ```bash
   yarn release
   ```

3. Publish to npm:
   ```bash
   npm publish
   ```

4. Push the changes and tags:
   ```bash
   git push --follow-tags origin main
   ```

## License

MIT