hetzner-storage-sdk 1.0.1

package/dist/HetznerStorageClient.js

@@ -0,0 +1,202 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObjectStorageProvider = exports.StorageShareProvider = exports.StorageBoxProvider = exports.BaseStorageProvider = exports.HetznerStorageClient = void 0;
+const BaseStorageProvider_1 = require("./providers/BaseStorageProvider");
+Object.defineProperty(exports, "BaseStorageProvider", { enumerable: true, get: function () { return BaseStorageProvider_1.BaseStorageProvider; } });
+const StorageBoxProvider_1 = require("./providers/StorageBoxProvider");
+Object.defineProperty(exports, "StorageBoxProvider", { enumerable: true, get: function () { return StorageBoxProvider_1.StorageBoxProvider; } });
+const StorageShareProvider_1 = require("./providers/StorageShareProvider");
+Object.defineProperty(exports, "StorageShareProvider", { enumerable: true, get: function () { return StorageShareProvider_1.StorageShareProvider; } });
+const ObjectStorageProvider_1 = require("./providers/ObjectStorageProvider");
+Object.defineProperty(exports, "ObjectStorageProvider", { enumerable: true, get: function () { return ObjectStorageProvider_1.ObjectStorageProvider; } });
+const env_config_1 = require("./utils/env-config");
+/**
+ * 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
+ * });
+ * ```
+ */
+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) {
+        if (!config.type) {
+            throw new Error('Storage type is required in configuration');
+        }
+        switch (config.type) {
+            case 'box': {
+                const envConfig = (0, env_config_1.loadStorageBoxEnv)();
+                const mergedConfig = (0, env_config_1.mergeWithEnv)(config, envConfig);
+                if (!mergedConfig.username || !mergedConfig.password) {
+                    throw new Error('Username and password are required for Storage Box. ' +
+                        'Provide them in config or set HETZNER_STORAGE_BOX_USERNAME and HETZNER_STORAGE_BOX_PASSWORD environment variables.');
+                }
+                return new StorageBoxProvider_1.StorageBoxProvider(mergedConfig);
+            }
+            case 'share': {
+                const envConfig = (0, env_config_1.loadStorageShareEnv)();
+                const mergedConfig = (0, env_config_1.mergeWithEnv)(config, envConfig);
+                if (!mergedConfig.username || !mergedConfig.password) {
+                    throw new Error('Username and password are required for Storage Share. ' +
+                        'Provide them in config or set HETZNER_STORAGE_SHARE_USERNAME and HETZNER_STORAGE_SHARE_PASSWORD environment variables.');
+                }
+                if (!mergedConfig.instance) {
+                    throw new Error('Instance is required for Storage Share. ' +
+                        'Provide it in config or set HETZNER_STORAGE_SHARE_INSTANCE environment variable.');
+                }
+                return new StorageShareProvider_1.StorageShareProvider(mergedConfig);
+            }
+            case 'object': {
+                const envConfig = (0, env_config_1.loadObjectStorageEnv)();
+                const mergedConfig = (0, env_config_1.mergeWithEnv)(config, envConfig);
+                if (!mergedConfig.accessKeyId || !mergedConfig.secretAccessKey) {
+                    throw new Error('accessKeyId and secretAccessKey are required for Object Storage. ' +
+                        'Provide them in config or set HETZNER_OBJECT_STORAGE_ACCESS_KEY_ID and HETZNER_OBJECT_STORAGE_SECRET_ACCESS_KEY environment variables.');
+                }
+                if (!mergedConfig.region) {
+                    throw new Error('Region is required for Object Storage. ' +
+                        'Provide it in config or set HETZNER_OBJECT_STORAGE_REGION environment variable.');
+                }
+                if (!mergedConfig.bucket) {
+                    throw new Error('Bucket is required for Object Storage. ' +
+                        'Provide it in config or set HETZNER_OBJECT_STORAGE_BUCKET environment variable.');
+                }
+                return new ObjectStorageProvider_1.ObjectStorageProvider(mergedConfig);
+            }
+            default:
+                throw new Error(`Invalid storage type: ${config.type}. Must be 'box', 'share', or 'object'.`);
+        }
+    }
+    /**
+     * 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 = {}) {
+        const envConfig = (0, env_config_1.loadStorageBoxEnv)();
+        const mergedConfig = (0, env_config_1.mergeWithEnv)({ ...config, type: 'box' }, envConfig);
+        if (!mergedConfig.username || !mergedConfig.password) {
+            throw new Error('Username and password are required for Storage Box. ' +
+                'Provide them in config or set HETZNER_STORAGE_BOX_USERNAME and HETZNER_STORAGE_BOX_PASSWORD environment variables.');
+        }
+        return new StorageBoxProvider_1.StorageBoxProvider(mergedConfig);
+    }
+    /**
+     * 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 = {}) {
+        const envConfig = (0, env_config_1.loadStorageShareEnv)();
+        const mergedConfig = (0, env_config_1.mergeWithEnv)({ ...config, type: 'share' }, envConfig);
+        if (!mergedConfig.username || !mergedConfig.password) {
+            throw new Error('Username and password are required for Storage Share. ' +
+                'Provide them in config or set HETZNER_STORAGE_SHARE_USERNAME and HETZNER_STORAGE_SHARE_PASSWORD environment variables.');
+        }
+        if (!mergedConfig.instance) {
+            throw new Error('Instance is required for Storage Share. ' +
+                'Provide it in config or set HETZNER_STORAGE_SHARE_INSTANCE environment variable.');
+        }
+        return new StorageShareProvider_1.StorageShareProvider(mergedConfig);
+    }
+    /**
+     * 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 = {}) {
+        const envConfig = (0, env_config_1.loadObjectStorageEnv)();
+        const mergedConfig = (0, env_config_1.mergeWithEnv)({ ...config, type: 'object' }, envConfig);
+        if (!mergedConfig.accessKeyId || !mergedConfig.secretAccessKey) {
+            throw new Error('accessKeyId and secretAccessKey are required for Object Storage. ' +
+                'Provide them in config or set HETZNER_OBJECT_STORAGE_ACCESS_KEY_ID and HETZNER_OBJECT_STORAGE_SECRET_ACCESS_KEY environment variables.');
+        }
+        if (!mergedConfig.region) {
+            throw new Error('Region is required for Object Storage. ' +
+                'Provide it in config or set HETZNER_OBJECT_STORAGE_REGION environment variable.');
+        }
+        if (!mergedConfig.bucket) {
+            throw new Error('Bucket is required for Object Storage. ' +
+                'Provide it in config or set HETZNER_OBJECT_STORAGE_BUCKET environment variable.');
+        }
+        return new ObjectStorageProvider_1.ObjectStorageProvider(mergedConfig);
+    }
+}
+exports.HetznerStorageClient = HetznerStorageClient;
+__exportStar(require("./types"), exports);

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Hetzner Storage SDK
+ *
+ * A TypeScript SDK for interacting with Hetzner Storage Box, Storage Share, and Object Storage
+ *
+ * @packageDocumentation
+ */
+export { HetznerStorageClient } from './HetznerStorageClient';
+export { BaseStorageProvider } from './providers/BaseStorageProvider';
+export { StorageBoxProvider } from './providers/StorageBoxProvider';
+export { StorageShareProvider } from './providers/StorageShareProvider';
+export { ObjectStorageProvider } from './providers/ObjectStorageProvider';
+export * from './types';
+export { RobotApiClient } from './utils/RobotApiClient';
+export { OcsApiClient } from './utils/OcsApiClient';
+export { S3ApiClient } from './utils/S3ApiClient';
+export { STORAGE_BOX_ENV, STORAGE_SHARE_ENV, OBJECT_STORAGE_ENV, loadStorageBoxEnv, loadStorageShareEnv, loadObjectStorageEnv, } from './utils/env-config';
+/**
+ * Default export is the HetznerStorageClient factory
+ */
+export { HetznerStorageClient as default } from './HetznerStorageClient';

package/dist/index.js

@@ -0,0 +1,56 @@
+"use strict";
+/**
+ * Hetzner Storage SDK
+ *
+ * A TypeScript SDK for interacting with Hetzner Storage Box, Storage Share, and Object Storage
+ *
+ * @packageDocumentation
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.loadObjectStorageEnv = exports.loadStorageShareEnv = exports.loadStorageBoxEnv = exports.OBJECT_STORAGE_ENV = exports.STORAGE_SHARE_ENV = exports.STORAGE_BOX_ENV = exports.S3ApiClient = exports.OcsApiClient = exports.RobotApiClient = exports.ObjectStorageProvider = exports.StorageShareProvider = exports.StorageBoxProvider = exports.BaseStorageProvider = exports.HetznerStorageClient = void 0;
+var HetznerStorageClient_1 = require("./HetznerStorageClient");
+Object.defineProperty(exports, "HetznerStorageClient", { enumerable: true, get: function () { return HetznerStorageClient_1.HetznerStorageClient; } });
+var BaseStorageProvider_1 = require("./providers/BaseStorageProvider");
+Object.defineProperty(exports, "BaseStorageProvider", { enumerable: true, get: function () { return BaseStorageProvider_1.BaseStorageProvider; } });
+var StorageBoxProvider_1 = require("./providers/StorageBoxProvider");
+Object.defineProperty(exports, "StorageBoxProvider", { enumerable: true, get: function () { return StorageBoxProvider_1.StorageBoxProvider; } });
+var StorageShareProvider_1 = require("./providers/StorageShareProvider");
+Object.defineProperty(exports, "StorageShareProvider", { enumerable: true, get: function () { return StorageShareProvider_1.StorageShareProvider; } });
+var ObjectStorageProvider_1 = require("./providers/ObjectStorageProvider");
+Object.defineProperty(exports, "ObjectStorageProvider", { enumerable: true, get: function () { return ObjectStorageProvider_1.ObjectStorageProvider; } });
+// Export all types
+__exportStar(require("./types"), exports);
+// Export utility clients for advanced usage
+var RobotApiClient_1 = require("./utils/RobotApiClient");
+Object.defineProperty(exports, "RobotApiClient", { enumerable: true, get: function () { return RobotApiClient_1.RobotApiClient; } });
+var OcsApiClient_1 = require("./utils/OcsApiClient");
+Object.defineProperty(exports, "OcsApiClient", { enumerable: true, get: function () { return OcsApiClient_1.OcsApiClient; } });
+var S3ApiClient_1 = require("./utils/S3ApiClient");
+Object.defineProperty(exports, "S3ApiClient", { enumerable: true, get: function () { return S3ApiClient_1.S3ApiClient; } });
+// Export environment configuration utilities
+var env_config_1 = require("./utils/env-config");
+Object.defineProperty(exports, "STORAGE_BOX_ENV", { enumerable: true, get: function () { return env_config_1.STORAGE_BOX_ENV; } });
+Object.defineProperty(exports, "STORAGE_SHARE_ENV", { enumerable: true, get: function () { return env_config_1.STORAGE_SHARE_ENV; } });
+Object.defineProperty(exports, "OBJECT_STORAGE_ENV", { enumerable: true, get: function () { return env_config_1.OBJECT_STORAGE_ENV; } });
+Object.defineProperty(exports, "loadStorageBoxEnv", { enumerable: true, get: function () { return env_config_1.loadStorageBoxEnv; } });
+Object.defineProperty(exports, "loadStorageShareEnv", { enumerable: true, get: function () { return env_config_1.loadStorageShareEnv; } });
+Object.defineProperty(exports, "loadObjectStorageEnv", { enumerable: true, get: function () { return env_config_1.loadObjectStorageEnv; } });
+/**
+ * Default export is the HetznerStorageClient factory
+ */
+var HetznerStorageClient_2 = require("./HetznerStorageClient");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return HetznerStorageClient_2.HetznerStorageClient; } });

package/dist/providers/BaseStorageProvider.d.ts

@@ -0,0 +1,73 @@
+import { Readable } from 'stream';
+import { FileMetadata, UploadOptions, DownloadOptions, StorageConfig } from '../types';
+/**
+ * Abstract base class for all storage providers
+ * Defines the common interface that both Storage Box and Storage Share must implement
+ */
+export declare abstract class BaseStorageProvider {
+    protected config: StorageConfig;
+    constructor(config: StorageConfig);
+    /**
+     * List files and directories at the specified path
+     * @param remotePath - The remote path to list (default: '/')
+     * @returns Array of file metadata
+     */
+    abstract listFiles(remotePath?: string): Promise<FileMetadata[]>;
+    /**
+     * Upload a file to the storage
+     * @param localPath - Local file path or Buffer or Readable stream
+     * @param remotePath - Remote destination path
+     * @param options - Upload options
+     */
+    abstract uploadFile(localPath: string | Buffer | Readable, remotePath: string, options?: UploadOptions): Promise<void>;
+    /**
+     * Download a file from the storage
+     * @param remotePath - Remote file path
+     * @param localPath - Local destination path (optional, returns Buffer if not provided)
+     * @param options - Download options
+     * @returns Buffer if localPath is not provided, void otherwise
+     */
+    abstract downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<Buffer | void>;
+    /**
+     * Delete a file or directory from the storage
+     * @param remotePath - Remote path to delete
+     */
+    abstract deleteFile(remotePath: string): Promise<void>;
+    /**
+     * Create a directory
+     * @param remotePath - Remote directory path to create
+     */
+    abstract createDirectory(remotePath: string): Promise<void>;
+    /**
+     * Move or rename a file/directory
+     * @param fromPath - Source path
+     * @param toPath - Destination path
+     */
+    abstract moveFile(fromPath: string, toPath: string): Promise<void>;
+    /**
+     * Copy a file/directory
+     * @param fromPath - Source path
+     * @param toPath - Destination path
+     */
+    abstract copyFile(fromPath: string, toPath: string): Promise<void>;
+    /**
+     * Check if a file or directory exists
+     * @param remotePath - Remote path to check
+     * @returns true if exists, false otherwise
+     */
+    abstract exists(remotePath: string): Promise<boolean>;
+    /**
+     * Get metadata for a specific file or directory
+     * @param remotePath - Remote path
+     * @returns File metadata
+     */
+    abstract getMetadata(remotePath: string): Promise<FileMetadata>;
+    /**
+     * Get the provider type
+     */
+    abstract getProviderType(): 'box' | 'share' | 'object';
+    /**
+     * Clean up resources and close connections
+     */
+    abstract disconnect(): Promise<void>;
+}

package/dist/providers/BaseStorageProvider.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BaseStorageProvider = void 0;
+/**
+ * Abstract base class for all storage providers
+ * Defines the common interface that both Storage Box and Storage Share must implement
+ */
+class BaseStorageProvider {
+    constructor(config) {
+        this.config = config;
+    }
+}
+exports.BaseStorageProvider = BaseStorageProvider;

package/dist/providers/ObjectStorageProvider.d.ts

@@ -0,0 +1,114 @@
+import { Readable } from 'stream';
+import { BaseStorageProvider } from './BaseStorageProvider';
+import { ObjectStorageConfig, FileMetadata, UploadOptions, DownloadOptions, BucketInfo, PresignedUrlOptions, MultipartUploadInfo, CompletedPart, ListObjectsOptions, ListObjectsResult } from '../types';
+/**
+ * Provider for Hetzner Object Storage (S3-compatible)
+ * Uses AWS SDK S3 client for all operations
+ */
+export declare class ObjectStorageProvider extends BaseStorageProvider {
+    private _config;
+    private s3Client;
+    private defaultBucket;
+    private initPromise;
+    constructor(config: ObjectStorageConfig);
+    /**
+     * Ensure the default bucket exists, creating it if necessary
+     */
+    private ensureBucketExists;
+    /**
+     * Wait for initialization to complete
+     */
+    private ensureInitialized;
+    /**
+     * Normalize a remote path to an S3 key by stripping leading slashes
+     */
+    private normalizeKey;
+    /**
+     * List files and directories at the specified path
+     */
+    listFiles(remotePath?: string): Promise<FileMetadata[]>;
+    /**
+     * Upload a file to the storage
+     */
+    uploadFile(localPath: string | Buffer | Readable, remotePath: string, options?: UploadOptions): Promise<void>;
+    /**
+     * Download a file from the storage
+     */
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<Buffer | void>;
+    /**
+     * Delete a file or directory from the storage
+     */
+    deleteFile(remotePath: string): Promise<void>;
+    /**
+     * Create a directory (S3 directory marker)
+     */
+    createDirectory(remotePath: string): Promise<void>;
+    /**
+     * Move or rename a file (copy + delete, since S3 has no native move)
+     */
+    moveFile(fromPath: string, toPath: string): Promise<void>;
+    /**
+     * Copy a file
+     */
+    copyFile(fromPath: string, toPath: string): Promise<void>;
+    /**
+     * Check if a file or directory exists
+     */
+    exists(remotePath: string): Promise<boolean>;
+    /**
+     * Get metadata for a specific file or directory
+     */
+    getMetadata(remotePath: string): Promise<FileMetadata>;
+    /**
+     * Get the provider type
+     */
+    getProviderType(): 'object';
+    /**
+     * Clean up resources
+     */
+    disconnect(): Promise<void>;
+    /**
+     * List all buckets
+     */
+    listBuckets(): Promise<BucketInfo[]>;
+    /**
+     * Create a new bucket
+     */
+    createBucket(name: string): Promise<void>;
+    /**
+     * Delete a bucket
+     */
+    deleteBucket(name: string): Promise<void>;
+    /**
+     * Check if a bucket exists
+     */
+    bucketExists(name: string): Promise<boolean>;
+    /**
+     * Generate a presigned download URL
+     */
+    getPresignedDownloadUrl(key: string, options?: PresignedUrlOptions): Promise<string>;
+    /**
+     * Generate a presigned upload URL
+     */
+    getPresignedUploadUrl(key: string, options?: PresignedUrlOptions): Promise<string>;
+    /**
+     * Initiate a multipart upload
+     */
+    createMultipartUpload(key: string, contentType?: string): Promise<MultipartUploadInfo>;
+    /**
+     * Upload a part of a multipart upload
+     */
+    uploadPart(key: string, uploadId: string, partNumber: number, body: Buffer): Promise<CompletedPart>;
+    /**
+     * Complete a multipart upload
+     */
+    completeMultipartUpload(key: string, uploadId: string, parts: CompletedPart[]): Promise<void>;
+    /**
+     * Abort a multipart upload
+     */
+    abortMultipartUpload(key: string, uploadId: string): Promise<void>;
+    /**
+     * List objects with pagination support
+     */
+    listObjectsPaginated(options?: ListObjectsOptions): Promise<ListObjectsResult>;
+}