@dcd-sdk/storage-client 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,171 @@
-# Temporary Holding Version
+# @dcd-sdk/storage-client
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Official Node.js & TypeScript Client SDK for **DevCloudDesk Storage Engine**.
+
+[![npm version](https://img.shields.io/npm/v/@dcd-sdk/storage-client?color=blue)](https://www.npmjs.com/package/@dcd-sdk/storage-client)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-18%2B-green)](https://nodejs.org/)
+
+High-performance, Cloudinary-compatible on-the-fly media transformations and ultra-fast asset delivery backed by your self-hosted DevCloudDesk storage clusters.
+
+---
+
+## 📦 Installation
+
+```bash
+# npm
+npm install @dcd-sdk/storage-client
+
+# pnpm
+pnpm add @dcd-sdk/storage-client
+
+# yarn
+yarn add @dcd-sdk/storage-client
+```
+
+Universal compatibility: **CommonJS (`require`)**, **ES Modules (`import`)**, **TypeScript**, **Next.js**, **Vite**, **Bun**, and **Deno**.
+
+---
+
+## 🚀 Quickstart
+
+### 1. Initialize the Client
+
+```typescript
+import { createBucketClient } from '@dcd-sdk/storage-client';
+
+const bucket = createBucketClient({
+  endpoint: 'http://YOUR_SERVER_IP:7100', // or https://storage.yourdomain.com
+  apiKey: process.env.STORAGE_API_KEY,    // API Key from DevCloudDesk Dashboard
+});
+```
+
+*CommonJS is also fully supported:*
+```javascript
+const { createBucketClient } = require('@dcd-sdk/storage-client');
+```
+
+---
+
+### 2. Uploading Files (Node.js or Browser)
+
+Supports file paths (Node.js), `Buffer`, `Blob`, `File`, or `ArrayBuffer`:
+
+```typescript
+// Upload from Buffer, File, or local file path
+const asset = await bucket.upload(fileBuffer, {
+  folder: 'avatars',
+  filename: 'user-profile.png',
+  onProgress: (percent) => {
+    console.log(`Upload progress: ${percent}%`);
+  },
+});
+
+console.log('Public ID:', asset.publicId);
+console.log('CDN URL:', asset.url);
+```
+
+---
+
+### 3. Dynamic On-The-Fly Transformations
+
+Generate real-time optimized WebP/AVIF images with automatic resizing, blur, and sharpening:
+
+```typescript
+const avatarUrl = bucket
+  .url(asset.publicId)
+  .resize({ width: 400, height: 400, crop: 'cover' })
+  .format('webp')
+  .quality(80)
+  .blur(4)
+  .build();
+
+// Output: http://YOUR_SERVER_IP:7100/v1/image/w_400,h_400,c_cover,f_webp,q_80,e_blur_4/avatars/user-profile.png
+```
+
+#### Transformation Options Reference
+
+| Method | Parameters | Description |
+| :--- | :--- | :--- |
+| `.resize({ width, height, crop })` | `number, number, CropMode` | Resizes image dimension with crop strategy |
+| `.crop(mode)` | `'fill' \| 'fit' \| 'crop' \| 'scale'` | Crop strategy |
+| `.format(fmt)` | `'auto' \| 'webp' \| 'avif' \| 'jpeg' \| 'png'` | Output image format |
+| `.quality(q)` | `number (1-100) \| 'auto'` | Compression quality |
+| `.blur(sigma)` | `number (1-100)` | Applies Gaussian blur filter |
+| `.grayscale()` | `boolean` | Converts image to black and white |
+| `.sharpen()` | `boolean` | Enhances edge sharpness |
+| `.rotation(deg)` | `number \| 'auto'` | Rotates image by degrees (e.g. 90, 180, 270) |
+
+---
+
+### 4. Client-Side Uploads via Signed Tokens (Zero Secret Exposure)
+
+Keep your master API keys safely on your backend server. Generate short-lived, tamper-proof signed upload tokens for your frontend React/Next.js/Mobile apps:
+
+```typescript
+// Backend endpoint (Node.js / Next.js / Express):
+app.post('/api/get-upload-token', async (req, res) => {
+  const tokenData = await bucket.createSignedUploadToken({
+    folder: 'user-uploads',
+    expiresInSeconds: 300,        // 5 minutes
+    maxBytes: 10 * 1024 * 1024,   // 10 MB limit
+  });
+  res.json(tokenData);
+});
+
+// Frontend client (Browser / React / Vue):
+const { token } = await res.json();
+await bucket.uploadWithToken(file, token, {
+  onProgress: (percent) => setProgress(percent),
+});
+```
+
+---
+
+### 5. Listing Files & Server Stats
+
+```typescript
+// List files in a bucket / folder
+const result = await bucket.listFiles({
+  folder: 'avatars',
+  page: 1,
+  limit: 20,
+});
+console.log('Files count:', result.data.files.length);
+
+// Server metrics
+const stats = await bucket.getStats();
+console.log('Total files:', stats.filesCount, 'Storage used:', stats.totalStorageBytes);
+```
+
+---
+
+### 6. Robust Error Handling
+
+```typescript
+import {
+  AuthenticationError,
+  NotFoundError,
+  PayloadTooLargeError,
+  UploadError,
+} from '@dcd-sdk/storage-client';
+
+try {
+  await bucket.upload(file);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    console.error('Check your API key:', error.message);
+  } else if (error instanceof PayloadTooLargeError) {
+    console.error('File size exceeds server limits:', error.message);
+  } else if (error instanceof UploadError) {
+    console.error('Upload failed:', error.message);
+  }
+}
+```
+
+---
+
+## 📄 License
+
+MIT © [DevCloudDesk](https://devclouddesk.com)

package/dist/index.d.mts

@@ -0,0 +1,214 @@
+type CropMode = 'fill' | 'fit' | 'crop' | 'scale';
+type OutputFormat = 'auto' | 'webp' | 'avif' | 'jpeg' | 'png';
+interface StorageClientConfig {
+    /** The base URL of the storage engine cluster (e.g. 'https://storage.mycoolapp.com' or 'http://192.168.1.50:7100') */
+    endpoint: string;
+    /** Public API key (dcd_pk_...), Secret key (dcd_sk_...), or Master key */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+type MediaClientConfig = StorageClientConfig;
+type BucketClientConfig = StorageClientConfig;
+interface TransformationOptions {
+    width?: number;
+    height?: number;
+    crop?: CropMode;
+    format?: OutputFormat;
+    quality?: number | 'auto';
+    blur?: number;
+    grayscale?: boolean;
+    sharpen?: boolean;
+    rotation?: number | 'auto';
+}
+interface UploadOptions {
+    folder?: string;
+    publicId?: string;
+    filename?: string;
+    overwrite?: boolean;
+    uniqueFilename?: boolean;
+    /** Optional client signed upload token (dcd_sig_...) to upload without API key */
+    token?: string;
+    tags?: string[];
+    /** Progress tracking callback (supported in browser environments) */
+    onProgress?: (percent: number) => void;
+    /** Request timeout in milliseconds */
+    timeoutMs?: number;
+}
+interface SignUploadOptions {
+    folder?: string;
+    maxBytes?: number;
+    expiresInSeconds?: number;
+}
+interface SignedUploadResult {
+    success: boolean;
+    token: string;
+    uploadUrl: string;
+    expiresInSeconds: number;
+    folder?: string | null;
+    maxBytes?: number | null;
+}
+interface AssetResult {
+    public_id: string;
+    publicId: string;
+    filename: string;
+    format: string;
+    resource_type?: string;
+    resourceType?: string;
+    width?: number;
+    height?: number;
+    bytes: number;
+    storageDriver: string;
+    etag: string;
+    url: string;
+    secure_url: string;
+    secureUrl: string;
+    rawUrl?: string;
+    created_at: number;
+    createdAt: number;
+}
+type StorageAssetResult = AssetResult;
+type BucketAssetResult = AssetResult;
+interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+interface FileListOptions {
+    folder?: string;
+    page?: number;
+    limit?: number;
+}
+interface FileListResult {
+    success: boolean;
+    data: {
+        files: AssetResult[];
+        pagination: Pagination;
+    };
+}
+interface ServerStats {
+    filesCount: number;
+    totalStorageBytes: number;
+    cacheVariantsCount: number;
+    cacheSizeBytes: number;
+    uptimeSeconds: number;
+    memoryUsageMb: number;
+    storageDriver: string;
+}
+interface HealthCheckResult {
+    status: 'ok' | 'error';
+    uptime?: number;
+    timestamp?: number;
+    version?: string;
+}
+
+declare class TransformationBuilder {
+    private endpoint;
+    private publicId;
+    private options;
+    constructor(endpoint: string, publicId: string);
+    width(w: number): this;
+    height(h: number): this;
+    resize(params: {
+        width?: number;
+        height?: number;
+        crop?: CropMode;
+    }): this;
+    crop(mode: CropMode): this;
+    format(fmt: OutputFormat): this;
+    quality(q: number | 'auto'): this;
+    blur(sigma?: number): this;
+    grayscale(enable?: boolean): this;
+    sharpen(enable?: boolean): this;
+    rotation(rot: number | 'auto'): this;
+    /**
+     * Builds the formatted transformation string (e.g. w_400,h_300,c_fill,f_auto)
+     */
+    toParamsString(): string;
+    /**
+     * Returns the final full URL string
+     */
+    build(): string;
+    toString(): string;
+}
+
+declare class StorageClient {
+    private endpoint;
+    private apiKey;
+    private defaultTimeoutMs;
+    constructor(config: StorageClientConfig);
+    /**
+     * Initializes a fluent URL builder for on-the-fly CDN image transformations
+     */
+    url(publicId: string): TransformationBuilder;
+    /**
+     * Checks the health and connectivity of the storage engine server
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Retrieves server performance, storage, and cache statistics (requires authorized API key)
+     */
+    getStats(): Promise<ServerStats>;
+    /**
+     * Lists files in the storage cluster with pagination and optional folder filter
+     */
+    listFiles(options?: FileListOptions): Promise<FileListResult>;
+    /**
+     * Generates a short-lived cryptographically signed upload token for safe client-side browser/mobile uploads.
+     * Keeps master API keys strictly on backend servers.
+     */
+    createSignedUploadToken(options?: SignUploadOptions): Promise<SignedUploadResult>;
+    /**
+     * Directly uploads a file to the storage server.
+     * Supports:
+     *  - String file path (Node.js)
+     *  - Buffer / Uint8Array / ArrayBuffer
+     *  - File / Blob (Browser and universal runtimes)
+     * Auth:
+     *  - Master API Key OR Client Signed Upload Token (dcd_sig_...)
+     */
+    upload(file: any, options?: UploadOptions): Promise<AssetResult>;
+    /**
+     * Helper method for frontend browser/mobile clients to upload using only a signed upload token (zero API key)
+     */
+    uploadWithToken(file: any, token: string, options?: Omit<UploadOptions, 'token'>): Promise<AssetResult>;
+    /**
+     * Permanently deletes a storage asset (requires API key with delete permissions)
+     */
+    delete(publicId: string): Promise<boolean>;
+    private getAuthHeaders;
+    private fetchWithTimeout;
+    private parseJsonResponse;
+}
+declare function createStorageClient(config: StorageClientConfig): StorageClient;
+declare const BucketClient: typeof StorageClient;
+type BucketClient = StorageClient;
+declare const createBucketClient: typeof createStorageClient;
+declare const MediaClient: typeof StorageClient;
+type MediaClient = StorageClient;
+declare const createMediaClient: typeof createStorageClient;
+
+declare class DCDStorageError extends Error {
+    status?: number;
+    code?: string;
+    details?: any;
+    constructor(message: string, status?: number, code?: string, details?: any);
+}
+declare class AuthenticationError extends DCDStorageError {
+    constructor(message?: string, status?: number, details?: any);
+}
+declare class NotFoundError extends DCDStorageError {
+    constructor(message?: string, status?: number, details?: any);
+}
+declare class PayloadTooLargeError extends DCDStorageError {
+    constructor(message?: string, status?: number, details?: any);
+}
+declare class UploadError extends DCDStorageError {
+    constructor(message: string, status?: number, details?: any);
+}
+
+export { AuthenticationError, BucketClient, DCDStorageError, MediaClient, NotFoundError, PayloadTooLargeError, StorageClient, TransformationBuilder, UploadError, createBucketClient, createMediaClient, createStorageClient };
+export type { AssetResult, BucketAssetResult, BucketClientConfig, CropMode, FileListOptions, FileListResult, HealthCheckResult, MediaClientConfig, OutputFormat, Pagination, ServerStats, SignUploadOptions, SignedUploadResult, StorageAssetResult, StorageClientConfig, TransformationOptions, UploadOptions };

package/dist/index.d.ts

@@ -0,0 +1,214 @@
+type CropMode = 'fill' | 'fit' | 'crop' | 'scale';
+type OutputFormat = 'auto' | 'webp' | 'avif' | 'jpeg' | 'png';
+interface StorageClientConfig {
+    /** The base URL of the storage engine cluster (e.g. 'https://storage.mycoolapp.com' or 'http://192.168.1.50:7100') */
+    endpoint: string;
+    /** Public API key (dcd_pk_...), Secret key (dcd_sk_...), or Master key */
+    apiKey?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeoutMs?: number;
+}
+type MediaClientConfig = StorageClientConfig;
+type BucketClientConfig = StorageClientConfig;
+interface TransformationOptions {
+    width?: number;
+    height?: number;
+    crop?: CropMode;
+    format?: OutputFormat;
+    quality?: number | 'auto';
+    blur?: number;
+    grayscale?: boolean;
+    sharpen?: boolean;
+    rotation?: number | 'auto';
+}
+interface UploadOptions {
+    folder?: string;
+    publicId?: string;
+    filename?: string;
+    overwrite?: boolean;
+    uniqueFilename?: boolean;
+    /** Optional client signed upload token (dcd_sig_...) to upload without API key */
+    token?: string;
+    tags?: string[];
+    /** Progress tracking callback (supported in browser environments) */
+    onProgress?: (percent: number) => void;
+    /** Request timeout in milliseconds */
+    timeoutMs?: number;
+}
+interface SignUploadOptions {
+    folder?: string;
+    maxBytes?: number;
+    expiresInSeconds?: number;
+}
+interface SignedUploadResult {
+    success: boolean;
+    token: string;
+    uploadUrl: string;
+    expiresInSeconds: number;
+    folder?: string | null;
+    maxBytes?: number | null;
+}
+interface AssetResult {
+    public_id: string;
+    publicId: string;
+    filename: string;
+    format: string;
+    resource_type?: string;
+    resourceType?: string;
+    width?: number;
+    height?: number;
+    bytes: number;
+    storageDriver: string;
+    etag: string;
+    url: string;
+    secure_url: string;
+    secureUrl: string;
+    rawUrl?: string;
+    created_at: number;
+    createdAt: number;
+}
+type StorageAssetResult = AssetResult;
+type BucketAssetResult = AssetResult;
+interface Pagination {
+    page: number;
+    limit: number;
+    total: number;
+    totalPages: number;
+    hasNext: boolean;
+    hasPrev: boolean;
+}
+interface FileListOptions {
+    folder?: string;
+    page?: number;
+    limit?: number;
+}
+interface FileListResult {
+    success: boolean;
+    data: {
+        files: AssetResult[];
+        pagination: Pagination;
+    };
+}
+interface ServerStats {
+    filesCount: number;
+    totalStorageBytes: number;
+    cacheVariantsCount: number;
+    cacheSizeBytes: number;
+    uptimeSeconds: number;
+    memoryUsageMb: number;
+    storageDriver: string;
+}
+interface HealthCheckResult {
+    status: 'ok' | 'error';
+    uptime?: number;
+    timestamp?: number;
+    version?: string;
+}
+
+declare class TransformationBuilder {
+    private endpoint;
+    private publicId;
+    private options;
+    constructor(endpoint: string, publicId: string);
+    width(w: number): this;
+    height(h: number): this;
+    resize(params: {
+        width?: number;
+        height?: number;
+        crop?: CropMode;
+    }): this;
+    crop(mode: CropMode): this;
+    format(fmt: OutputFormat): this;
+    quality(q: number | 'auto'): this;
+    blur(sigma?: number): this;
+    grayscale(enable?: boolean): this;
+    sharpen(enable?: boolean): this;
+    rotation(rot: number | 'auto'): this;
+    /**
+     * Builds the formatted transformation string (e.g. w_400,h_300,c_fill,f_auto)
+     */
+    toParamsString(): string;
+    /**
+     * Returns the final full URL string
+     */
+    build(): string;
+    toString(): string;
+}
+
+declare class StorageClient {
+    private endpoint;
+    private apiKey;
+    private defaultTimeoutMs;
+    constructor(config: StorageClientConfig);
+    /**
+     * Initializes a fluent URL builder for on-the-fly CDN image transformations
+     */
+    url(publicId: string): TransformationBuilder;
+    /**
+     * Checks the health and connectivity of the storage engine server
+     */
+    healthCheck(): Promise<HealthCheckResult>;
+    /**
+     * Retrieves server performance, storage, and cache statistics (requires authorized API key)
+     */
+    getStats(): Promise<ServerStats>;
+    /**
+     * Lists files in the storage cluster with pagination and optional folder filter
+     */
+    listFiles(options?: FileListOptions): Promise<FileListResult>;
+    /**
+     * Generates a short-lived cryptographically signed upload token for safe client-side browser/mobile uploads.
+     * Keeps master API keys strictly on backend servers.
+     */
+    createSignedUploadToken(options?: SignUploadOptions): Promise<SignedUploadResult>;
+    /**
+     * Directly uploads a file to the storage server.
+     * Supports:
+     *  - String file path (Node.js)
+     *  - Buffer / Uint8Array / ArrayBuffer
+     *  - File / Blob (Browser and universal runtimes)
+     * Auth:
+     *  - Master API Key OR Client Signed Upload Token (dcd_sig_...)
+     */
+    upload(file: any, options?: UploadOptions): Promise<AssetResult>;
+    /**
+     * Helper method for frontend browser/mobile clients to upload using only a signed upload token (zero API key)
+     */
+    uploadWithToken(file: any, token: string, options?: Omit<UploadOptions, 'token'>): Promise<AssetResult>;
+    /**
+     * Permanently deletes a storage asset (requires API key with delete permissions)
+     */
+    delete(publicId: string): Promise<boolean>;
+    private getAuthHeaders;
+    private fetchWithTimeout;
+    private parseJsonResponse;
+}
+declare function createStorageClient(config: StorageClientConfig): StorageClient;
+declare const BucketClient: typeof StorageClient;
+type BucketClient = StorageClient;
+declare const createBucketClient: typeof createStorageClient;
+declare const MediaClient: typeof StorageClient;
+type MediaClient = StorageClient;
+declare const createMediaClient: typeof createStorageClient;
+
+declare class DCDStorageError extends Error {
+    status?: number;
+    code?: string;
+    details?: any;
+    constructor(message: string, status?: number, code?: string, details?: any);
+}
+declare class AuthenticationError extends DCDStorageError {
+    constructor(message?: string, status?: number, details?: any);
+}
+declare class NotFoundError extends DCDStorageError {
+    constructor(message?: string, status?: number, details?: any);
+}
+declare class PayloadTooLargeError extends DCDStorageError {
+    constructor(message?: string, status?: number, details?: any);
+}
+declare class UploadError extends DCDStorageError {
+    constructor(message: string, status?: number, details?: any);
+}
+
+export { AuthenticationError, BucketClient, DCDStorageError, MediaClient, NotFoundError, PayloadTooLargeError, StorageClient, TransformationBuilder, UploadError, createBucketClient, createMediaClient, createStorageClient };
+export type { AssetResult, BucketAssetResult, BucketClientConfig, CropMode, FileListOptions, FileListResult, HealthCheckResult, MediaClientConfig, OutputFormat, Pagination, ServerStats, SignUploadOptions, SignedUploadResult, StorageAssetResult, StorageClientConfig, TransformationOptions, UploadOptions };