hetzner-storage-sdk 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sajan
+
+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,539 @@
+# Hetzner Storage SDK
+
+A comprehensive TypeScript SDK for interacting with Hetzner Storage Box and Storage Share (Nextcloud).
+
+## Features
+
+- 🔧 **Dual Provider Support**: Works with both Storage Box and Storage Share
+- 📦 **WebDAV Protocol**: Reliable file operations via WebDAV
+- 🔒 **Type-Safe**: Full TypeScript support with complete type definitions
+- 🎯 **Factory Pattern**: Easy provider switching with unified interface
+- 📊 **Management APIs**: Full support for Robot API and Nextcloud OCS API
+- 🚀 **Modern Async/Await**: Promise-based API throughout
+
+## Installation
+
+```bash
+npm install hetzner-storage-sdk
+# or
+yarn add hetzner-storage-sdk
+```
+
+## Quick Start
+
+### Storage Box (WebDAV)
+
+```typescript
+import { HetznerStorageClient } from 'hetzner-storage-sdk';
+
+const client = HetznerStorageClient.create({
+  type: 'box',
+  username: 'u123456',
+  password: 'your-password',
+  storageBoxId: '12345',
+  robotUsername: 'robot-user', // Optional: for management operations
+  robotPassword: 'robot-pass'
+});
+
+// List files
+const files = await client.listFiles('/');
+
+// Upload a file
+await client.uploadFile('./local-file.txt', '/remote-file.txt');
+
+// Download a file
+await client.downloadFile('/remote-file.txt', './downloaded-file.txt');
+
+// Create snapshot (requires Robot API credentials)
+const snapshot = await client.createSnapshot('My backup');
+```
+
+### Storage Share (Nextcloud)
+
+```typescript
+import { HetznerStorageClient } from 'hetzner-storage-sdk';
+
+const client = HetznerStorageClient.create({
+  type: 'share',
+  username: 'your-username',
+  password: 'your-password',
+  instance: 'u123456' // Your instance ID
+});
+
+// List files
+const files = await client.listFiles('/');
+
+// Upload a file
+await client.uploadFile('./document.pdf', '/documents/document.pdf');
+
+// Create a public share link
+const share = await client.createPublicShare(
+  '/documents/document.pdf',
+  'optional-password',
+  '2024-12-31', // Expiration date
+  1 // Permissions (1 = read)
+);
+
+console.log('Share URL:', share.url);
+```
+
+## Configuration
+
+### Storage Box Configuration
+
+```typescript
+interface StorageBoxConfig {
+  type: 'box';
+  username: string;           // Storage Box username (e.g., 'u123456')
+  password: string;           // Storage Box password
+  storageBoxId?: string;      // Required for management operations
+  robotUsername?: string;     // Robot API username
+  robotPassword?: string;     // Robot API password
+}
+```
+
+### Storage Share Configuration
+
+```typescript
+interface StorageShareConfig {
+  type: 'share';
+  username: string;  // Your Nextcloud username
+  password: string;  // Your Nextcloud password
+  instance: string;  // Instance ID (e.g., 'u123456')
+}
+```
+
+## API Reference
+
+### Common Methods (Both Providers)
+
+#### File Operations
+
+```typescript
+// List files in a directory
+listFiles(remotePath?: string): Promise<FileMetadata[]>
+
+// Upload a file
+uploadFile(
+  localPath: string | Buffer | Readable,
+  remotePath: string,
+  options?: UploadOptions
+): Promise<void>
+
+// Download a file
+downloadFile(
+  remotePath: string,
+  localPath?: string,
+  options?: DownloadOptions
+): Promise<Buffer | void>
+
+// Delete a file or directory
+deleteFile(remotePath: string): Promise<void>
+
+// Create a directory
+createDirectory(remotePath: string): Promise<void>
+
+// Move/rename a file
+moveFile(fromPath: string, toPath: string): Promise<void>
+
+// Copy a file
+copyFile(fromPath: string, toPath: string): Promise<void>
+
+// Check if file exists
+exists(remotePath: string): Promise<boolean>
+
+// Get file metadata
+getMetadata(remotePath: string): Promise<FileMetadata>
+
+// Close connections
+disconnect(): Promise<void>
+```
+
+### Storage Box Specific Methods
+
+#### Robot API Management
+
+```typescript
+// List all storage boxes
+listStorageBoxes(): Promise<StorageBoxDetails[]>
+
+// Get storage box details
+getStorageBoxDetails(): Promise<StorageBoxDetails>
+
+// Toggle services (SSH, Samba, WebDAV)
+toggleServices(services: {
+  webdav?: boolean;
+  samba?: boolean;
+  ssh?: boolean;
+}): Promise<StorageBoxDetails>
+
+// Snapshot management
+createSnapshot(comment?: string): Promise<SnapshotInfo>
+listSnapshots(): Promise<SnapshotInfo[]>
+deleteSnapshot(snapshotName: string): Promise<void>
+revertToSnapshot(snapshotName: string): Promise<void>
+```
+
+### Storage Share Specific Methods
+
+#### OCS API Share Management
+
+```typescript
+// Create a public link share
+createPublicShare(
+  path: string,
+  password?: string,
+  expireDate?: string,
+  permissions?: number
+): Promise<OCSShareData>
+
+// Create a user share
+createUserShare(
+  path: string,
+  shareWith: string,
+  permissions?: number
+): Promise<OCSShareData>
+
+// Create a group share
+createGroupShare(
+  path: string,
+  shareWith: string,
+  permissions?: number
+): Promise<OCSShareData>
+
+// List all shares
+listShares(): Promise<OCSShareData[]>
+
+// Get share details
+getShare(shareId: string): Promise<OCSShareData>
+
+// Update a share
+updateShare(
+  shareId: string,
+  options: Partial<CreateShareOptions>
+): Promise<OCSShareData>
+
+// Delete a share
+deleteShare(shareId: string): Promise<void>
+
+// Get shares for a specific path
+getSharesForPath(path: string): Promise<OCSShareData[]>
+```
+
+## Usage Examples
+
+### Example 1: Backup with Snapshot (Storage Box)
+
+```typescript
+import { HetznerStorageClient } from 'hetzner-storage-sdk';
+
+async function createBackup() {
+  const client = HetznerStorageClient.create({
+    type: 'box',
+    username: 'u123456',
+    password: 'your-password',
+    storageBoxId: '12345',
+    robotUsername: 'robot-user',
+    robotPassword: 'robot-pass'
+  });
+
+  // Upload backup files
+  await client.createDirectory('/backups');
+  await client.uploadFile('./database.sql', '/backups/database.sql');
+  
+  // Create snapshot
+  const snapshot = await client.createSnapshot('Daily backup');
+  console.log('Snapshot created:', snapshot.name);
+  
+  // List all snapshots
+  const snapshots = await client.listSnapshots();
+  console.log('Total snapshots:', snapshots.length);
+  
+  await client.disconnect();
+}
+```
+
+### Example 2: Share Files with Team (Storage Share)
+
+```typescript
+import { HetznerStorageClient } from 'hetzner-storage-sdk';
+
+async function shareWithTeam() {
+  const client = HetznerStorageClient.create({
+    type: 'share',
+    username: 'your-username',
+    password: 'your-password',
+    instance: 'u123456'
+  });
+
+  // Upload document
+  await client.uploadFile('./report.pdf', '/team/report.pdf');
+  
+  // Create public share with password
+  const publicShare = await client.createPublicShare(
+    '/team/report.pdf',
+    'secure-password',
+    '2024-12-31',
+    1 // Read-only
+  );
+  
+  console.log('Share link:', publicShare.url);
+  console.log('Password:', 'secure-password');
+  
+  // Also share with specific team member
+  const userShare = await client.createUserShare(
+    '/team/report.pdf',
+    'john.doe',
+    31 // Full permissions
+  );
+  
+  console.log('Shared with john.doe');
+  
+  await client.disconnect();
+}
+```
+
+### Example 3: Sync Local Directory (Storage Box)
+
+```typescript
+import { HetznerStorageClient } from 'hetzner-storage-sdk';
+import { readdir } from 'fs/promises';
+import { join } from 'path';
+
+async function syncDirectory(localDir: string, remoteDir: string) {
+  const client = HetznerStorageClient.create({
+    type: 'box',
+    username: 'u123456',
+    password: 'your-password'
+  });
+
+  // Create remote directory if it doesn't exist
+  if (!(await client.exists(remoteDir))) {
+    await client.createDirectory(remoteDir);
+  }
+
+  // Get local files
+  const localFiles = await readdir(localDir);
+
+  // Upload each file
+  for (const file of localFiles) {
+    const localPath = join(localDir, file);
+    const remotePath = `${remoteDir}/${file}`;
+    
+    console.log(`Uploading ${file}...`);
+    await client.uploadFile(localPath, remotePath, { overwrite: true });
+  }
+
+  console.log(`Synced ${localFiles.length} files`);
+  await client.disconnect();
+}
+```
+
+### Example 4: Download and Process Files
+
+```typescript
+import { HetznerStorageClient } from 'hetzner-storage-sdk';
+
+async function processFiles() {
+  const client = HetznerStorageClient.create({
+    type: 'box',
+    username: 'u123456',
+    password: 'your-password'
+  });
+
+  // List all CSV files
+  const files = await client.listFiles('/data');
+  const csvFiles = files.filter(f => f.filename.endsWith('.csv'));
+
+  for (const file of csvFiles) {
+    // Download as buffer (not to disk)
+    const buffer = await client.downloadFile(file.path) as Buffer;
+    const content = buffer.toString('utf-8');
+    
+    // Process content
+    console.log(`Processing ${file.filename}`);
+    const lines = content.split('\n');
+    console.log(`  - ${lines.length} lines`);
+    
+    // Your processing logic here...
+  }
+
+  await client.disconnect();
+}
+```
+
+### Example 5: Automated Backup Rotation
+
+```typescript
+import { HetznerStorageClient } from 'hetzner-storage-sdk';
+
+async function rotateBackups() {
+  const client = HetznerStorageClient.create({
+    type: 'box',
+    username: 'u123456',
+    password: 'your-password',
+    storageBoxId: '12345',
+    robotUsername: 'robot-user',
+    robotPassword: 'robot-pass'
+  });
+
+  const backupDir = '/backups';
+  const maxBackups = 7; // Keep last 7 backups
+
+  // Create new backup
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const currentBackup = `${backupDir}/${timestamp}`;
+  
+  await client.createDirectory(currentBackup);
+  await client.uploadFile('./data.tar.gz', `${currentBackup}/data.tar.gz`);
+  
+  // Create snapshot
+  await client.createSnapshot(`Backup ${timestamp}`);
+
+  // Get all backups
+  const backups = await client.listFiles(backupDir);
+  
+  // Delete old backups
+  if (backups.length > maxBackups) {
+    const sortedBackups = backups.sort((a, b) => 
+      a.lastModified.getTime() - b.lastModified.getTime()
+    );
+    
+    const toDelete = sortedBackups.slice(0, backups.length - maxBackups);
+    for (const backup of toDelete) {
+      await client.deleteFile(backup.path);
+      console.log(`Deleted old backup: ${backup.filename}`);
+    }
+  }
+
+  await client.disconnect();
+}
+```
+
+## Error Handling
+
+```typescript
+import { HetznerStorageClient, StorageError } from 'hetzner-storage-sdk';
+
+async function handleErrors() {
+  const client = HetznerStorageClient.create({
+    type: 'box',
+    username: 'u123456',
+    password: 'your-password'
+  });
+
+  try {
+    await client.uploadFile('./file.txt', '/remote/file.txt');
+  } catch (error) {
+    if (error instanceof Error) {
+      const storageError = error as StorageError;
+      console.error('Error:', storageError.message);
+      console.error('Code:', storageError.code);
+      console.error('Status:', storageError.statusCode);
+    }
+  } finally {
+    await client.disconnect();
+  }
+}
+```
+
+## Architecture
+
+The SDK follows a clean architecture with:
+
+- **Factory Pattern**: `HetznerStorageClient` creates the appropriate provider
+- **Provider Pattern**: Abstract `BaseStorageProvider` with concrete implementations
+- **Separation of Concerns**: 
+  - File operations via WebDAV
+  - Management via Robot API (Storage Box) or OCS API (Storage Share)
+
+```
+┌─────────────────────────────────┐
+│   HetznerStorageClient          │
+│   (Factory)                     │
+└─────────────┬───────────────────┘
+              │
+      ┌───────┴────────┐
+      │                │
+┌─────▼─────┐    ┌────▼──────┐
+│ Storage   │    │ Storage   │
+│ Box       │    │ Share     │
+│ Provider  │    │ Provider  │
+└─────┬─────┘    └────┬──────┘
+      │                │
+  ┌───┴───┐        ┌───┴───┐
+  │WebDAV │        │WebDAV │
+  │Robot  │        │  OCS  │
+  │  API  │        │  API  │
+  └───────┘        └───────┘
+```
+
+## Protocol Details
+
+### WebDAV Operations
+
+Both Storage Box and Storage Share use WebDAV for file operations:
+
+- **PROPFIND**: List directory contents
+- **PUT**: Upload files
+- **GET**: Download files
+- **DELETE**: Remove files/directories
+- **MKCOL**: Create directories
+- **MOVE**: Move/rename files
+- **COPY**: Copy files
+
+### Storage Box URL Format
+```
+https://<username>.your-storagebox.de/
+```
+
+### Storage Share URL Format
+```
+https://<instance>.your-storageshare.de/remote.php/dav/files/<username>/
+```
+
+## TypeScript Support
+
+The SDK is written in TypeScript and provides full type definitions:
+
+```typescript
+import { 
+  HetznerStorageClient,
+  StorageBoxConfig,
+  StorageShareConfig,
+  FileMetadata,
+  StorageBoxDetails,
+  SnapshotInfo,
+  OCSShareData
+} from 'hetzner-storage-sdk';
+
+// Full autocomplete and type checking
+const client = HetznerStorageClient.create({
+  type: 'box',
+  username: 'u123456',
+  password: 'pass'
+});
+
+const files: FileMetadata[] = await client.listFiles('/');
+```
+
+## Dependencies
+
+- **axios**: HTTP client for API requests
+- **webdav**: WebDAV client for file operations
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## Support
+
+For issues or questions:
+- Check the examples in the documentation
+- Review the type definitions for detailed API information
+- Open an issue on the project repository
+- [Contact Me](mailto:work@sajankumarv.com)

package/dist/HetznerStorageClient.d.ts

@@ -0,0 +1,103 @@
+import { BaseStorageProvider } from './providers/BaseStorageProvider';
+import { StorageBoxProvider } from './providers/StorageBoxProvider';
+import { StorageShareProvider } from './providers/StorageShareProvider';
+import { ObjectStorageProvider } from './providers/ObjectStorageProvider';
+import { StorageConfig, ObjectStorageConfig, StorageBoxConfig, StorageShareConfig } from './types';
+/**
+ * Factory class for creating Hetzner Storage clients
+ *
+ * This class implements the Factory pattern to instantiate the appropriate
+ * storage provider based on the configuration.
+ *
+ * Configuration can be provided explicitly or loaded from environment variables.
+ * Explicit configuration takes precedence over environment variables.
+ *
+ * Environment Variables:
+ * - Storage Box:
+ *   - HETZNER_STORAGE_BOX_USERNAME
+ *   - HETZNER_STORAGE_BOX_PASSWORD
+ *   - HETZNER_STORAGE_BOX_PROTOCOL (optional: webdav)
+ *   - HETZNER_STORAGE_BOX_ID (optional)
+ *   - HETZNER_ROBOT_USERNAME (optional)
+ *   - HETZNER_ROBOT_PASSWORD (optional)
+ *
+ * - Storage Share:
+ *   - HETZNER_STORAGE_SHARE_USERNAME
+ *   - HETZNER_STORAGE_SHARE_PASSWORD
+ *   - HETZNER_STORAGE_SHARE_INSTANCE
+ *
+ * - Object Storage:
+ *   - HETZNER_OBJECT_STORAGE_ACCESS_KEY_ID
+ *   - HETZNER_OBJECT_STORAGE_SECRET_ACCESS_KEY
+ *   - HETZNER_OBJECT_STORAGE_REGION
+ *   - HETZNER_OBJECT_STORAGE_BUCKET
+ *
+ * Usage:
+ * ```typescript
+ * // Using explicit configuration
+ * const client = HetznerStorageClient.create({
+ *   type: 'box',
+ *   username: 'u123456',
+ *   password: 'your-password',
+ * });
+ *
+ * // Using environment variables (set env vars first)
+ * const client = HetznerStorageClient.create({ type: 'box' });
+ *
+ * // Mixed: override specific values while loading others from env
+ * const client = HetznerStorageClient.create({
+ *   type: 'object',
+ *   bucket: 'my-custom-bucket' // Other fields loaded from env
+ * });
+ * ```
+ */
+export declare class HetznerStorageClient {
+    /**
+     * Create a new storage client based on the provided configuration
+     *
+     * Configuration values can be provided explicitly or loaded from environment variables.
+     * Explicitly provided values take precedence over environment variables.
+     *
+     * @param config - Storage configuration object (partial config allowed if env vars are set)
+     * @returns An instance of the appropriate storage provider
+     * @throws Error if the storage type is invalid or required configuration is missing
+     */
+    static create(config: Partial<StorageConfig> & {
+        type: StorageConfig['type'];
+    }): BaseStorageProvider;
+    /**
+     * Create a Storage Box client
+     * Convenience method for creating a Storage Box provider
+     *
+     * Configuration values can be provided explicitly or loaded from environment variables.
+     *
+     * @param config - Storage Box configuration (optional if env vars are set)
+     * @returns StorageBoxProvider instance
+     */
+    static createBoxClient(config?: Partial<Omit<StorageBoxConfig, 'type'>>): StorageBoxProvider;
+    /**
+     * Create a Storage Share client
+     * Convenience method for creating a Storage Share provider
+     *
+     * Configuration values can be provided explicitly or loaded from environment variables.
+     *
+     * @param config - Storage Share configuration (optional if env vars are set)
+     * @returns StorageShareProvider instance
+     */
+    static createShareClient(config?: Partial<Omit<StorageShareConfig, 'type'>>): StorageShareProvider;
+    /**
+     * Create an Object Storage client
+     * Convenience method for creating an Object Storage provider
+     *
+     * Configuration values can be provided explicitly or loaded from environment variables.
+     *
+     * @param config - Object Storage configuration (optional if env vars are set)
+     * @returns ObjectStorageProvider instance
+     */
+    static createObjectClient(config?: Partial<Omit<ObjectStorageConfig, 'type'>>): ObjectStorageProvider;
+}
+/**
+ * Re-export for convenience
+ */
+export { BaseStorageProvider, StorageBoxProvider, StorageShareProvider, ObjectStorageProvider };
+export * from './types';