wolfronix-sdk 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wolfronix
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,351 @@
+# @wolfronix/sdk
+
+Official JavaScript/TypeScript SDK for Wolfronix - Zero-knowledge encryption made simple.
+
+[![npm version](https://badge.fury.io/js/@wolfronix%2Fsdk.svg)](https://www.npmjs.com/package/@wolfronix/sdk)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+## Features
+
+- 🔐 **Zero-Knowledge Encryption** - 4-layer enterprise-grade security
+- 🚀 **Simple API** - Encrypt files in 2 lines of code
+- 📦 **TypeScript Native** - Full type definitions included
+- 🌐 **Universal** - Works in Node.js and browsers
+- ⚡ **Streaming** - Handle large files with progress tracking
+- 🔄 **Auto Retry** - Built-in retry logic with exponential backoff
+
+## Installation
+
+```bash
+npm install @wolfronix/sdk
+# or
+yarn add @wolfronix/sdk
+# or
+pnpm add @wolfronix/sdk
+```
+
+## Quick Start
+
+```typescript
+import Wolfronix from '@wolfronix/sdk';
+
+// Initialize client
+const wfx = new Wolfronix({
+  baseUrl: 'https://your-wolfronix-server:5002',
+  clientId: 'your-client-id' // Optional for enterprise mode
+});
+
+// Login
+await wfx.login('user@example.com', 'password123');
+
+// Encrypt a file
+const result = await wfx.encrypt(file);
+console.log('Encrypted! File ID:', result.file_id);
+
+// Decrypt a file
+const decrypted = await wfx.decrypt(result.file_id);
+```
+
+## Usage Examples
+
+### Browser (React, Vue, Angular, etc.)
+
+```typescript
+import Wolfronix from '@wolfronix/sdk';
+
+const wfx = new Wolfronix('https://wolfronix-server:5002');
+
+// With file input
+const handleFileUpload = async (event: React.ChangeEvent<HTMLInputElement>) => {
+  const file = event.target.files?.[0];
+  if (!file) return;
+
+  try {
+    const { file_id } = await wfx.encrypt(file);
+    console.log('File encrypted:', file_id);
+  } catch (error) {
+    console.error('Encryption failed:', error);
+  }
+};
+
+// Download decrypted file
+const handleDownload = async (fileId: string, filename: string) => {
+  const blob = await wfx.decrypt(fileId);
+  
+  // Create download link
+  const url = URL.createObjectURL(blob);
+  const a = document.createElement('a');
+  a.href = url;
+  a.download = filename;
+  a.click();
+  URL.revokeObjectURL(url);
+};
+```
+
+### Node.js
+
+```typescript
+import Wolfronix from '@wolfronix/sdk';
+import * as fs from 'fs';
+
+const wfx = new Wolfronix({
+  baseUrl: 'https://wolfronix-server:5002',
+  clientId: 'your-client-id',
+  insecure: true // For self-signed certs in development
+});
+
+async function main() {
+  // Login
+  await wfx.login('user@example.com', 'password123');
+
+  // Encrypt a file
+  const fileBuffer = fs.readFileSync('document.pdf');
+  const { file_id } = await wfx.encrypt(fileBuffer, 'document.pdf');
+  console.log('Encrypted file ID:', file_id);
+
+  // List all files
+  const { files } = await wfx.listFiles();
+  console.log('Your files:', files);
+
+  // Decrypt and save
+  const decrypted = await wfx.decryptToBuffer(file_id);
+  fs.writeFileSync('decrypted.pdf', Buffer.from(decrypted));
+}
+
+main();
+```
+
+### Large File Streaming with Progress
+
+```typescript
+const wfx = new Wolfronix('https://wolfronix-server:5002');
+
+// Encrypt with progress
+const result = await wfx.encryptStream(largeFile, (percent) => {
+  console.log(`Uploading: ${percent}%`);
+  progressBar.value = percent;
+});
+
+// Decrypt with progress
+const blob = await wfx.decryptStream(fileId, (percent) => {
+  console.log(`Downloading: ${percent}%`);
+});
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new Wolfronix(config: WolfronixConfig | string)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `baseUrl` | string | required | Wolfronix server URL |
+| `clientId` | string | `''` | Enterprise client ID |
+| `timeout` | number | `30000` | Request timeout (ms) |
+| `retries` | number | `3` | Max retry attempts |
+| `insecure` | boolean | `false` | Skip SSL verification |
+
+### Authentication
+
+| Method | Description |
+|--------|-------------|
+| `register(email, password)` | Register new user |
+| `login(email, password)` | Login existing user |
+| `setToken(token, userId?)` | Set auth token directly |
+| `logout()` | Clear authentication |
+| `isAuthenticated()` | Check auth status |
+| `getUserId()` | Get current user ID |
+
+### File Operations
+
+| Method | Description |
+|--------|-------------|
+| `encrypt(file, filename?)` | Encrypt and store file |
+| `encryptStream(file, onProgress?)` | Encrypt large file with progress |
+| `decrypt(fileId)` | Decrypt file (returns Blob) |
+| `decryptToBuffer(fileId)` | Decrypt file (returns ArrayBuffer) |
+| `decryptStream(fileId, onProgress?)` | Decrypt large file with progress |
+| `listFiles()` | List user's encrypted files |
+| `deleteFile(fileId)` | Delete encrypted file |
+
+### Utility
+
+| Method | Description |
+|--------|-------------|
+| `getMetrics()` | Get encryption/decryption stats |
+| `healthCheck()` | Check server availability |
+
+## Error Handling
+
+The SDK provides specific error types for different scenarios:
+
+```typescript
+import Wolfronix, { 
+  WolfronixError,
+  AuthenticationError,
+  FileNotFoundError,
+  PermissionDeniedError,
+  NetworkError,
+  ValidationError
+} from '@wolfronix/sdk';
+
+try {
+  await wfx.encrypt(file);
+} catch (error) {
+  if (error instanceof AuthenticationError) {
+    // Token expired, redirect to login
+    router.push('/login');
+  } else if (error instanceof FileNotFoundError) {
+    // File doesn't exist
+    showToast('File not found');
+  } else if (error instanceof PermissionDeniedError) {
+    // Not your file
+    showToast('Access denied');
+  } else if (error instanceof NetworkError) {
+    // Server unreachable
+    showToast('Connection failed. Retrying...');
+  } else if (error instanceof ValidationError) {
+    // Invalid input
+    showToast(error.message);
+  } else {
+    // Unknown error
+    console.error('Unexpected error:', error);
+  }
+}
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and includes full type definitions:
+
+```typescript
+import Wolfronix, {
+  WolfronixConfig,
+  AuthResponse,
+  EncryptResponse,
+  FileInfo,
+  ListFilesResponse,
+  MetricsResponse
+} from '@wolfronix/sdk';
+
+// All methods are fully typed
+const config: WolfronixConfig = {
+  baseUrl: 'https://server:5002',
+  clientId: 'my-client'
+};
+
+const wfx = new Wolfronix(config);
+const response: EncryptResponse = await wfx.encrypt(file);
+```
+
+## React Hook Example
+
+```typescript
+// useWolfronix.ts
+import { useState, useCallback, useMemo } from 'react';
+import Wolfronix, { FileInfo as WolfronixFile } from '@wolfronix/sdk';
+
+export function useWolfronix(baseUrl: string, clientId?: string) {
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const [files, setFiles] = useState<WolfronixFile[]>([]);
+
+  const client = useMemo(() => new Wolfronix({ baseUrl, clientId }), [baseUrl, clientId]);
+
+  const login = useCallback(async (email: string, password: string) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      return await client.login(email, password);
+    } catch (e) {
+      setError(e as Error);
+      throw e;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client]);
+
+  const encrypt = useCallback(async (file: File) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      const result = await client.encrypt(file);
+      await refreshFiles();
+      return result;
+    } catch (e) {
+      setError(e as Error);
+      throw e;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client]);
+
+  const decrypt = useCallback(async (fileId: string) => {
+    setIsLoading(true);
+    setError(null);
+    try {
+      return await client.decrypt(fileId);
+    } catch (e) {
+      setError(e as Error);
+      throw e;
+    } finally {
+      setIsLoading(false);
+    }
+  }, [client]);
+
+  const refreshFiles = useCallback(async () => {
+    const { files } = await client.listFiles();
+    setFiles(files);
+  }, [client]);
+
+  return {
+    client,
+    isLoading,
+    error,
+    files,
+    login,
+    encrypt,
+    decrypt,
+    refreshFiles
+  };
+}
+
+// Usage in component
+function FileManager() {
+  const { files, encrypt, decrypt, isLoading } = useWolfronix(
+    'https://wolfronix:5002',
+    'my-client-id'
+  );
+
+  return (
+    <div>
+      <input type="file" onChange={(e) => encrypt(e.target.files![0])} />
+      {isLoading && <Spinner />}
+      {files.map(f => (
+        <div key={f.file_id} onClick={() => decrypt(f.file_id)}>
+          {f.original_name}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Requirements
+
+- Node.js 16+ (for Node.js usage)
+- Modern browser with Fetch API support
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.
+
+## Links
+
+- [Documentation](https://wolfronix.com/docs)
+- [API Reference](https://wolfronix.com/docs/api)
+- [GitHub](https://github.com/wolfronix/sdk-javascript)
+- [Report Issues](https://github.com/wolfronix/sdk-javascript/issues)

package/dist/index.d.mts

@@ -0,0 +1,238 @@
+/**
+ * Wolfronix SDK for JavaScript/TypeScript
+ * Zero-knowledge encryption made simple
+ *
+ * @package @wolfronix/sdk
+ * @version 1.0.0
+ */
+interface WolfronixConfig {
+    /** Wolfronix server base URL */
+    baseUrl: string;
+    /** Your enterprise client ID (optional for self-hosted) */
+    clientId?: string;
+    /** Request timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Retry failed requests (default: 3) */
+    retries?: number;
+    /** Skip SSL verification for self-signed certs (default: false) */
+    insecure?: boolean;
+}
+interface AuthResponse {
+    success: boolean;
+    user_id: string;
+    token: string;
+    message: string;
+}
+interface EncryptResponse {
+    success: boolean;
+    file_id: string;
+    original_name: string;
+    encrypted_size: number;
+    message: string;
+}
+interface FileInfo {
+    file_id: string;
+    original_name: string;
+    encrypted_size: number;
+    created_at: string;
+}
+interface ListFilesResponse {
+    success: boolean;
+    files: FileInfo[];
+    total: number;
+}
+interface DeleteResponse {
+    success: boolean;
+    message: string;
+}
+interface MetricsResponse {
+    success: boolean;
+    total_encryptions: number;
+    total_decryptions: number;
+    total_bytes_encrypted: number;
+    total_bytes_decrypted: number;
+}
+interface StreamToken {
+    token: string;
+    expires_at: string;
+}
+declare class WolfronixError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    readonly details?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, details?: Record<string, unknown>);
+}
+declare class AuthenticationError extends WolfronixError {
+    constructor(message?: string);
+}
+declare class FileNotFoundError extends WolfronixError {
+    constructor(fileId: string);
+}
+declare class PermissionDeniedError extends WolfronixError {
+    constructor(message?: string);
+}
+declare class NetworkError extends WolfronixError {
+    constructor(message?: string);
+}
+declare class ValidationError extends WolfronixError {
+    constructor(message: string);
+}
+declare class Wolfronix {
+    private readonly config;
+    private token;
+    private userId;
+    private tokenExpiry;
+    /**
+     * Create a new Wolfronix client
+     *
+     * @example
+     * ```typescript
+     * const wfx = new Wolfronix({
+     *   baseUrl: 'https://wolfronix-server:5002',
+     *   clientId: 'your-client-id'
+     * });
+     * ```
+     */
+    constructor(config: WolfronixConfig | string);
+    private getHeaders;
+    private request;
+    private sleep;
+    private ensureAuthenticated;
+    /**
+     * Register a new user
+     *
+     * @example
+     * ```typescript
+     * const { user_id, token } = await wfx.register('user@example.com', 'password123');
+     * ```
+     */
+    register(email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Login with existing credentials
+     *
+     * @example
+     * ```typescript
+     * await wfx.login('user@example.com', 'password123');
+     * ```
+     */
+    login(email: string, password: string): Promise<AuthResponse>;
+    /**
+     * Set authentication token directly (useful for server-side apps)
+     *
+     * @example
+     * ```typescript
+     * wfx.setToken('jwt-token-here', 'user-id-here');
+     * ```
+     */
+    setToken(token: string, userId?: string): void;
+    /**
+     * Clear authentication state (logout)
+     */
+    logout(): void;
+    /**
+     * Check if client is authenticated
+     */
+    isAuthenticated(): boolean;
+    /**
+     * Get current user ID
+     */
+    getUserId(): string | null;
+    /**
+     * Encrypt and store a file
+     *
+     * @example
+     * ```typescript
+     * // Browser
+     * const fileInput = document.querySelector('input[type="file"]');
+     * const result = await wfx.encrypt(fileInput.files[0]);
+     *
+     * // Node.js
+     * const buffer = fs.readFileSync('document.pdf');
+     * const result = await wfx.encrypt(buffer, 'document.pdf');
+     * ```
+     */
+    encrypt(file: File | Blob | ArrayBuffer | Uint8Array, filename?: string): Promise<EncryptResponse>;
+    /**
+     * Encrypt a file using streaming (for large files)
+     *
+     * @example
+     * ```typescript
+     * const result = await wfx.encryptStream(largeFile, (progress) => {
+     *   console.log(`Progress: ${progress}%`);
+     * });
+     * ```
+     */
+    encryptStream(file: File | Blob, onProgress?: (percent: number) => void): Promise<EncryptResponse>;
+    /**
+     * Decrypt and retrieve a file
+     *
+     * @example
+     * ```typescript
+     * // Get as Blob (browser)
+     * const blob = await wfx.decrypt('file-id');
+     * const url = URL.createObjectURL(blob);
+     *
+     * // Get as Buffer (Node.js)
+     * const buffer = await wfx.decryptToBuffer('file-id');
+     * fs.writeFileSync('decrypted.pdf', buffer);
+     * ```
+     */
+    decrypt(fileId: string): Promise<Blob>;
+    /**
+     * Decrypt and return as ArrayBuffer
+     */
+    decryptToBuffer(fileId: string): Promise<ArrayBuffer>;
+    /**
+     * Decrypt using streaming (for large files)
+     */
+    decryptStream(fileId: string, onProgress?: (percent: number) => void): Promise<Blob>;
+    /**
+     * List all encrypted files for current user
+     *
+     * @example
+     * ```typescript
+     * const { files } = await wfx.listFiles();
+     * files.forEach(f => console.log(f.original_name, f.file_id));
+     * ```
+     */
+    listFiles(): Promise<ListFilesResponse>;
+    /**
+     * Delete an encrypted file
+     *
+     * @example
+     * ```typescript
+     * await wfx.deleteFile('file-id');
+     * ```
+     */
+    deleteFile(fileId: string): Promise<DeleteResponse>;
+    /**
+     * Get encryption/decryption metrics
+     *
+     * @example
+     * ```typescript
+     * const metrics = await wfx.getMetrics();
+     * console.log(`Total encryptions: ${metrics.total_encryptions}`);
+     * ```
+     */
+    getMetrics(): Promise<MetricsResponse>;
+    /**
+     * Check if server is healthy
+     */
+    healthCheck(): Promise<boolean>;
+}
+/**
+ * Create a new Wolfronix client
+ *
+ * @example
+ * ```typescript
+ * import { createClient } from '@wolfronix/sdk';
+ *
+ * const wfx = createClient({
+ *   baseUrl: 'https://wolfronix-server:5002',
+ *   clientId: 'your-client-id'
+ * });
+ * ```
+ */
+declare function createClient(config: WolfronixConfig | string): Wolfronix;
+
+export { type AuthResponse, AuthenticationError, type DeleteResponse, type EncryptResponse, type FileInfo, FileNotFoundError, type ListFilesResponse, type MetricsResponse, NetworkError, PermissionDeniedError, type StreamToken, ValidationError, Wolfronix, type WolfronixConfig, WolfronixError, createClient, Wolfronix as default };