@owlmeans/storage-resource 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 OwlMeans Common — Fullstack typescript framework
+
+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,512 @@
+# @owlmeans/storage-resource
+
+Object storage resource integration for OwlMeans Common applications. This package provides S3-compatible object storage functionality with file upload, download, type validation, and stream processing capabilities designed for secure file management in distributed applications.
+
+## Overview
+
+The `@owlmeans/storage-resource` package extends the OwlMeans resource system to provide object storage functionality including:
+
+- **S3-Compatible Storage**: Integration with AWS S3 and S3-compatible storage services
+- **File Upload/Download**: Secure file operations with validation and type checking
+- **Stream Processing**: Efficient handling of file streams for large files
+- **Type Validation**: Automatic file type detection and validation
+- **Prefix Management**: Organized file storage with configurable prefixes
+- **Resource Integration**: Seamless integration with OwlMeans resource management system
+
+This package follows the OwlMeans resource pattern and provides server-side storage capabilities for applications requiring file management.
+
+## Installation
+
+```bash
+npm install @owlmeans/storage-resource
+```
+
+## Dependencies
+
+This package requires and integrates with:
+- `@owlmeans/resource`: Base resource management system
+- `@owlmeans/server-context`: Server context management
+- `@owlmeans/storage-common`: Storage utilities and error types
+- `@aws-sdk/client-s3`: AWS S3 SDK for storage operations
+- `file-type`: File type detection utilities
+
+## Core Concepts
+
+### Storage Resource
+
+A specialized resource that manages file storage operations including upload, download, and metadata management through S3-compatible APIs.
+
+### File Validation
+
+Built-in file type validation ensures that uploaded files match their declared MIME types, providing security against file type spoofing.
+
+### Stream Processing
+
+Efficient handling of file streams allows for processing large files without excessive memory usage.
+
+### Bucket Configuration
+
+Support for multiple storage buckets with different configurations for organizing files by purpose or security level.
+
+## API Reference
+
+### Types
+
+#### `StoredRecord`
+Interface for stored file records extending ResourceRecord.
+
+```typescript
+interface StoredRecord extends ResourceRecord {
+  url?: string                    // File URL for access
+  size?: number                   // File size in bytes
+  prefix: string                  // Storage prefix/path
+  stream?: Readable               // File stream for upload
+  format?: StoredFileFormat       // File format information
+  type?: string                   // MIME type
+  bytes?: Uint8Array             // File bytes (alternative to stream)
+  base64?: string                // Base64 encoded file data
+}
+```
+
+#### `StorageConfig`
+Configuration for storage bucket access.
+
+```typescript
+interface StorageConfig {
+  url: string          // Storage service URL
+  apiKey: string       // API key in format "keyId:keySecret"
+  basePrefix: string   // Base prefix for all files in this bucket
+}
+```
+
+#### `StorageResource`
+Resource interface for storage operations.
+
+```typescript
+interface StorageResource extends Resource<StoredRecord> {
+  // Inherits all Resource methods for CRUD operations
+  // Specialized for file storage with validation
+}
+```
+
+#### `StoredConfigAppend`
+Configuration extension for storage bucket definitions.
+
+```typescript
+interface StoredConfigAppend {
+  storageBuckets: { [key: string]: StorageConfig }
+}
+```
+
+### Factory Functions
+
+#### `createStorageResource(alias?: string, configKey?: string): StorageResource`
+
+Creates a storage resource instance with S3-compatible operations.
+
+**Parameters:**
+- `alias` (optional): Resource alias (default: `DEFAULT_ALIAS`)
+- `configKey` (optional): Configuration key for bucket selection (defaults to alias)
+
+**Returns:** StorageResource instance
+
+**Features:**
+- File upload with type validation
+- Stream processing for efficient memory usage
+- S3-compatible storage operations
+- Automatic file type detection
+- Error handling for storage operations
+
+**Example:**
+```typescript
+import { createStorageResource } from '@owlmeans/storage-resource'
+
+const storageResource = createStorageResource('files', 'main-bucket')
+
+// Use with context
+context.registerResource(storageResource)
+await context.configure().init()
+
+// Upload file
+const uploadedFile = await storageResource.create({
+  stream: fileStream,
+  size: fileSize,
+  type: 'image/jpeg',
+  prefix: 'uploads/images'
+})
+```
+
+### Storage Operations
+
+#### File Upload
+
+Upload files with validation and type checking:
+
+```typescript
+const fileRecord = {
+  stream: fileStream,           // Readable stream
+  size: fileSize,              // File size in bytes
+  type: 'image/jpeg',          // Expected MIME type
+  prefix: 'uploads/avatars'    // Storage prefix
+}
+
+try {
+  const storedFile = await storageResource.create(fileRecord)
+  console.log(`File uploaded: ${storedFile.url}`)
+} catch (error) {
+  if (error instanceof FileTypeError) {
+    // Handle file type mismatch
+  } else if (error instanceof FileStreamError) {
+    // Handle stream errors
+  }
+}
+```
+
+#### File Retrieval
+
+Retrieve file metadata and URLs:
+
+```typescript
+// Get file by ID
+const file = await storageResource.get(fileId)
+console.log(`File URL: ${file.url}`)
+
+// Search files by prefix
+const files = await storageResource.list({
+  filter: { prefix: 'uploads/images' }
+})
+```
+
+### Error Handling
+
+The package provides specific error types for storage operations:
+
+#### `FileStreamError`
+Thrown when file stream is missing or invalid.
+
+```typescript
+if (record.stream == null) {
+  throw new FileStreamError('no')
+}
+```
+
+#### `FilePropertyError`
+Thrown when required file properties are missing.
+
+```typescript
+if (record.size == null) {
+  throw new FilePropertyError('size')
+}
+```
+
+#### `FileTypeError`
+Thrown when file type doesn't match declared MIME type.
+
+```typescript
+if (type?.mime !== record.type) {
+  throw new FileTypeError('mime-mismatch')
+}
+```
+
+#### `StorageApiError`
+Thrown when storage API operations fail.
+
+### Constants
+
+#### `DEFAULT_ALIAS`
+Default alias for storage resources.
+
+```typescript
+const DEFAULT_ALIAS = 'storage'
+```
+
+## Usage Examples
+
+### Basic Storage Setup
+
+```typescript
+import { createStorageResource } from '@owlmeans/storage-resource'
+import { makeServerContext } from '@owlmeans/server-context'
+
+// Configure server context with storage buckets
+const context = makeServerContext({
+  service: 'file-service',
+  type: AppType.Backend,
+  layer: Layer.Service,
+  storageBuckets: {
+    'main': {
+      url: 'my-bucket.s3.amazonaws.com',
+      apiKey: 'AKIAIOSFODNN7EXAMPLE:wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY',
+      basePrefix: 'files'
+    }
+  }
+})
+
+// Create and register storage resource
+const storageResource = createStorageResource('storage', 'main')
+context.registerResource(storageResource)
+
+await context.configure().init()
+
+// Storage resource is now ready for use
+```
+
+### File Upload with Validation
+
+```typescript
+import { Readable } from 'stream'
+
+const uploadFile = async (fileBuffer: Buffer, mimeType: string, filename: string) => {
+  const fileStream = Readable.from(fileBuffer)
+  
+  try {
+    const uploadedFile = await storageResource.create({
+      stream: fileStream,
+      size: fileBuffer.length,
+      type: mimeType,
+      prefix: `uploads/${new Date().getFullYear()}`
+    })
+    
+    return {
+      id: uploadedFile.id,
+      url: uploadedFile.url,
+      size: uploadedFile.size
+    }
+  } catch (error) {
+    if (error instanceof FileTypeError) {
+      throw new Error('File type mismatch - uploaded file doesn\'t match declared type')
+    } else if (error instanceof FilePropertyError) {
+      throw new Error('Missing required file properties')
+    } else {
+      throw new Error('File upload failed')
+    }
+  }
+}
+```
+
+### Multiple Storage Buckets
+
+```typescript
+const context = makeServerContext({
+  service: 'multi-storage-app',
+  storageBuckets: {
+    'public': {
+      url: 'public-bucket.s3.amazonaws.com',
+      apiKey: 'public-key:public-secret',
+      basePrefix: 'public'
+    },
+    'private': {
+      url: 'private-bucket.s3.amazonaws.com', 
+      apiKey: 'private-key:private-secret',
+      basePrefix: 'private'
+    }
+  }
+})
+
+// Create resources for different buckets
+const publicStorage = createStorageResource('public-storage', 'public')
+const privateStorage = createStorageResource('private-storage', 'private')
+
+context.registerResource(publicStorage)
+context.registerResource(privateStorage)
+
+await context.configure().init()
+
+// Upload to public bucket
+const publicFile = await publicStorage.create({
+  stream: publicFileStream,
+  size: fileSize,
+  type: 'image/jpeg',
+  prefix: 'avatars'
+})
+
+// Upload to private bucket
+const privateFile = await privateStorage.create({
+  stream: privateFileStream,
+  size: fileSize,
+  type: 'application/pdf',
+  prefix: 'documents'
+})
+```
+
+### File Type Validation
+
+```typescript
+const uploadWithValidation = async (fileStream: Readable, declaredType: string, size: number) => {
+  try {
+    const result = await storageResource.create({
+      stream: fileStream,
+      size: size,
+      type: declaredType,
+      prefix: 'validated-uploads'
+    })
+    
+    console.log('File upload successful with type validation')
+    return result
+  } catch (error) {
+    if (error instanceof FileTypeError) {
+      console.error('File type validation failed - file content doesn\'t match declared MIME type')
+      throw error
+    }
+    throw error
+  }
+}
+
+// Example usage
+const jpegStream = fs.createReadStream('image.jpg')
+await uploadWithValidation(jpegStream, 'image/jpeg', jpegStats.size)
+```
+
+### Alternative Upload Methods
+
+```typescript
+// Upload from bytes
+const uploadFromBytes = async (bytes: Uint8Array, type: string) => {
+  const stream = Readable.from(Buffer.from(bytes))
+  
+  return await storageResource.create({
+    stream: stream,
+    size: bytes.length,
+    type: type,
+    prefix: 'byte-uploads'
+  })
+}
+
+// Upload from base64
+const uploadFromBase64 = async (base64Data: string, type: string) => {
+  const buffer = Buffer.from(base64Data, 'base64')
+  const stream = Readable.from(buffer)
+  
+  return await storageResource.create({
+    stream: stream,
+    size: buffer.length,
+    type: type,
+    prefix: 'base64-uploads'
+  })
+}
+```
+
+### File Retrieval and Management
+
+```typescript
+// Get file metadata
+const getFileInfo = async (fileId: string) => {
+  const file = await storageResource.get(fileId)
+  
+  return {
+    id: file.id,
+    url: file.url,
+    size: file.size,
+    type: file.type,
+    prefix: file.prefix
+  }
+}
+
+// List files by prefix
+const listFilesByPrefix = async (prefix: string) => {
+  const files = await storageResource.list({
+    filter: { prefix: prefix }
+  })
+  
+  return files.map(file => ({
+    id: file.id,
+    url: file.url,
+    size: file.size
+  }))
+}
+
+// Delete file
+const deleteFile = async (fileId: string) => {
+  await storageResource.remove(fileId)
+}
+```
+
+## Configuration
+
+### Storage Bucket Configuration
+
+Configure storage buckets in your server configuration:
+
+```typescript
+interface ServerConfig {
+  // ... other configuration
+  storageBuckets: {
+    [bucketAlias: string]: {
+      url: string          // S3 endpoint URL
+      apiKey: string       // Access key ID and secret key separated by ':'
+      basePrefix: string   // Base prefix for all files
+    }
+  }
+}
+```
+
+### Environment Variables
+
+Typical environment-based configuration:
+
+```typescript
+const config = {
+  storageBuckets: {
+    main: {
+      url: process.env.S3_BUCKET_URL,
+      apiKey: `${process.env.S3_ACCESS_KEY}:${process.env.S3_SECRET_KEY}`,
+      basePrefix: process.env.S3_BASE_PREFIX || 'files'
+    }
+  }
+}
+```
+
+## Security Considerations
+
+### File Type Validation
+- Always validate file types to prevent malicious uploads
+- Use MIME type detection from file content, not just extensions
+- Implement file size limits to prevent abuse
+
+### Access Control
+- Use separate buckets for different security levels
+- Implement proper API key management and rotation
+- Consider signed URLs for temporary access
+
+### Storage Security
+- Use HTTPS for all storage operations
+- Implement proper bucket policies and access controls
+- Monitor storage access and usage patterns
+
+## Performance Considerations
+
+- **Stream Processing**: Use streams for large files to minimize memory usage
+- **File Size Limits**: Implement appropriate file size limits
+- **Concurrent Uploads**: Consider rate limiting for multiple concurrent uploads
+- **CDN Integration**: Use CDN for frequently accessed files
+
+## Integration with OwlMeans Ecosystem
+
+This package integrates with:
+
+- **@owlmeans/resource**: Base resource management patterns
+- **@owlmeans/server-context**: Server context and configuration
+- **@owlmeans/storage-common**: Shared storage utilities and errors
+
+## Best Practices
+
+1. **Validate file types** always from content, not just filename
+2. **Use appropriate prefixes** to organize files logically
+3. **Implement file size limits** to prevent abuse
+4. **Handle errors gracefully** with specific error types
+5. **Use separate buckets** for different security levels
+6. **Monitor storage usage** and implement cleanup policies
+
+## Related Packages
+
+- **@owlmeans/storage-common**: Storage utilities and error types
+- **@owlmeans/resource**: Base resource management
+- **@owlmeans/server-context**: Server context management
+
+## AWS S3 Compatibility
+
+This package works with:
+- **AWS S3**: Native Amazon S3 service
+- **MinIO**: Self-hosted S3-compatible storage
+- **DigitalOcean Spaces**: S3-compatible cloud storage
+- **Other S3-compatible services**: Any service implementing S3 API

package/build/consts.d.ts

@@ -0,0 +1,3 @@
+export declare const DEFAULT_ALIAS = "s3-storage";
+export declare const supportedMimeTypes: import("file-type").MimeType[];
+//# sourceMappingURL=consts.d.ts.map

package/build/consts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.d.ts","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAEA,eAAO,MAAM,aAAa,eAAe,CAAA;AAEzC,eAAO,MAAM,kBAAkB,gCAAiB,CAAA"}

package/build/consts.js

@@ -0,0 +1,4 @@
+import { supportedMimeTypes as mimeTypes } from 'file-type';
+export const DEFAULT_ALIAS = 's3-storage';
+export const supportedMimeTypes = [...mimeTypes];
+//# sourceMappingURL=consts.js.map

package/build/consts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"consts.js","sourceRoot":"","sources":["../src/consts.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,kBAAkB,IAAI,SAAS,EAAE,MAAM,WAAW,CAAA;AAE3D,MAAM,CAAC,MAAM,aAAa,GAAG,YAAY,CAAA;AAEzC,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,GAAG,SAAS,CAAC,CAAA"}

package/build/helper.d.ts

@@ -0,0 +1,3 @@
+import type { StoredFile, StoredFileWithData } from '@owlmeans/storage-common';
+export declare const stripData: <Input extends StoredFileWithData, Output extends StoredFile>(file: Input) => Output;
+//# sourceMappingURL=helper.d.ts.map

package/build/helper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.d.ts","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAA;AAE9E,eAAO,MAAM,SAAS,GACpB,KAAK,SAAS,kBAAkB,EAChC,MAAM,SAAS,UAAU,QACnB,KAAK,KAAG,MAgBf,CAAA"}

package/build/helper.js

@@ -0,0 +1,13 @@
+export const stripData = (file) => {
+    const intermediate = { ...file };
+    if (intermediate.format) {
+        delete intermediate.format;
+    }
+    intermediate.instances = Object.fromEntries(Object.entries(file.instances).map(([key, instance]) => [key, {
+            size: instance.size,
+            alias: instance.alias,
+            url: instance.url,
+        }]));
+    return JSON.parse(JSON.stringify(intermediate));
+};
+//# sourceMappingURL=helper.js.map

package/build/helper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helper.js","sourceRoot":"","sources":["../src/helper.ts"],"names":[],"mappings":"AAEA,MAAM,CAAC,MAAM,SAAS,GAAG,CAGvB,IAAW,EAAU,EAAE;IACvB,MAAM,YAAY,GAAU,EAAE,GAAG,IAAI,EAAE,CAAA;IAEvC,IAAI,YAAY,CAAC,MAAM,EAAE,CAAC;QACxB,OAAO,YAAY,CAAC,MAAM,CAAA;IAC5B,CAAC;IAED,YAAY,CAAC,SAAS,GAAG,MAAM,CAAC,WAAW,CACzC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,EAAE;YAC5D,IAAI,EAAE,QAAQ,CAAC,IAAI;YACnB,KAAK,EAAE,QAAQ,CAAC,KAAK;YACrB,GAAG,EAAE,QAAQ,CAAC,GAAG;SAClB,CAAC,CAAC,CACJ,CAAA;IAED,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,YAAY,CAAC,CAAW,CAAA;AAC3D,CAAC,CAAA"}

package/build/index.d.ts

@@ -0,0 +1,5 @@
+export type * from './types.js';
+export * from './consts.js';
+export * from './helper.js';
+export * from './resource.js';
+//# sourceMappingURL=index.d.ts.map

package/build/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/build/index.js

@@ -0,0 +1,4 @@
+export * from './consts.js';
+export * from './helper.js';
+export * from './resource.js';
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA"}

package/build/model.d.ts

@@ -0,0 +1 @@
+//# sourceMappingURL=model.d.ts.map

package/build/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":""}

package/build/model.js

@@ -0,0 +1,2 @@
+"use strict";
+//# sourceMappingURL=model.js.map

package/build/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":""}

package/build/resource.d.ts

@@ -0,0 +1,4 @@
+import type { Config, Context, StorageResource } from './types.js';
+export declare const createStorageResource: (alias?: string, configKey?: string) => StorageResource;
+export declare const appendStorageResource: <C extends Config, T extends Context<C>>(ctx: T, alias?: string, configKey?: string) => T;
+//# sourceMappingURL=resource.d.ts.map

package/build/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAgB,MAAM,YAAY,CAAA;AAShF,eAAO,MAAM,qBAAqB,WAAW,MAAM,cAA8B,MAAM,oBAuEtF,CAAA;AAED,eAAO,MAAM,qBAAqB,GAAI,CAAC,SAAS,MAAM,EAAE,CAAC,SAAS,OAAO,CAAC,CAAC,CAAC,OACrE,CAAC,UAAS,MAAM,cAA8B,MAAM,KACxD,CAMF,CAAA"}

package/build/resource.js

@@ -0,0 +1,72 @@
+import { appendContextual } from '@owlmeans/context';
+import { DEFAULT_ALIAS } from './consts.js';
+import { FilePropertyError, FileStreamError, FileTypeError, StorageApiError } from '@owlmeans/storage-common';
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3';
+import { ResilientError } from '@owlmeans/error';
+import { fileTypeFromBuffer } from 'file-type';
+export const createStorageResource = (alias = DEFAULT_ALIAS, configKey) => {
+    configKey ??= alias;
+    const resource = appendContextual(alias, {
+        create: async (record, _opts) => {
+            if (record.stream == null) {
+                throw new FileStreamError('no');
+            }
+            if (record.size == null) {
+                throw new FilePropertyError('size');
+            }
+            // @TODO Do something here - it would be fixed if we do not convert
+            // multipart into buffer by means integrated into fastify
+            const buffers = await record.stream.toArray();
+            const buffer = buffers[0];
+            const type = await fileTypeFromBuffer(buffer);
+            if (type?.mime !== record.type) {
+                throw new FileTypeError('mime-mismatch');
+            }
+            const context = resource.assertCtx();
+            const config = context.cfg.storageBuckets[configKey];
+            const [keyId, keySecret] = config.apiKey.split(':');
+            const [bucket, ...parts] = config.url.split('.');
+            // @TODO Abstract it some way and make the upload multipart
+            try {
+                const client = new S3Client({
+                    region: 'eu-central-1',
+                    endpoint: `https://${parts.join('.')}`,
+                    credentials: {
+                        accessKeyId: keyId,
+                        secretAccessKey: keySecret,
+                    }
+                });
+                const result = await client.send(new PutObjectCommand({
+                    ACL: 'public-read',
+                    Bucket: bucket,
+                    Body: Buffer.concat(buffers),
+                    Key: `${config.basePrefix}/${record.prefix}`,
+                    ContentLength: record.size,
+                    ContentDisposition: 'inline',
+                    ContentType: record.type,
+                }));
+                if (result.$metadata.httpStatusCode !== 200) {
+                    throw new StorageApiError('code');
+                }
+                record.url = `https://${config.url}/${config.basePrefix}/${record.prefix}`;
+                delete record.stream;
+                client.destroy();
+            }
+            catch (e) {
+                if (e instanceof ResilientError) {
+                    throw e;
+                }
+                console.error(e);
+                throw new StorageApiError();
+            }
+            return record;
+        }
+    });
+    return resource;
+};
+export const appendStorageResource = (ctx, alias = DEFAULT_ALIAS, configKey) => {
+    const resource = createStorageResource(alias, configKey);
+    ctx.registerResource(resource);
+    return ctx;
+};
+//# sourceMappingURL=resource.js.map

package/build/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,31 @@
+import type { Resource, ResourceRecord } from '@owlmeans/resource';
+import type { StoredFileFormat } from '@owlmeans/storage-common';
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context';
+import type { Readable } from 'stream';
+export interface StoredRecord extends ResourceRecord {
+    url?: string;
+    size?: number;
+    prefix: string;
+    stream?: Readable;
+    format?: StoredFileFormat;
+    type?: string;
+    bytes?: Uint8Array;
+    base64?: string;
+}
+export interface StoredConfigAppend {
+    storageBuckets: {
+        [key: string]: StorageConfig;
+    };
+}
+export interface StorageConfig {
+    url: string;
+    apiKey: string;
+    basePrefix: string;
+}
+export interface StorageResource extends Resource<StoredRecord> {
+}
+export interface Config extends ServerConfig, StoredConfigAppend {
+}
+export interface Context<C extends Config = Config> extends ServerContext<C> {
+}
+//# sourceMappingURL=types.d.ts.map

package/build/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AAClE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAChE,OAAO,KAAK,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAA;AAC3E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAA;AAEtC,MAAM,WAAW,YAAa,SAAQ,cAAc;IAClD,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,QAAQ,CAAA;IACjB,MAAM,CAAC,EAAE,gBAAgB,CAAA;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,UAAU,CAAA;IAClB,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE;QAAE,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,CAAA;KAAE,CAAA;CACjD;AAED,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,eAAgB,SAAQ,QAAQ,CAAC,YAAY,CAAC;CAC9D;AAED,MAAM,WAAW,MAAO,SAAQ,YAAY,EAAE,kBAAkB;CAAI;AACpE,MAAM,WAAW,OAAO,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,CAAE,SAAQ,aAAa,CAAC,CAAC,CAAC;CAAI"}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@owlmeans/storage-resource",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -b",
+    "dev": "sleep 393 && nodemon -e ts,tsx,json --watch src --exec \"tsc -p ./tsconfig.json\"",
+    "watch": "tsc -b -w --preserveWatchOutput --pretty"
+  },
+  "main": "build/index.js",
+  "module": "build/index.js",
+  "types": "build/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./build/index.js",
+      "require": "./build/index.js",
+      "default": "./build/index.js",
+      "module": "./build/index.js",
+      "types": "./build/index.d.ts"
+    }
+  },
+  "peerDependencies": {
+    "react": "*"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.701.0",
+    "@owlmeans/context": "^0.1.0",
+    "@owlmeans/error": "^0.1.0",
+    "@owlmeans/resource": "^0.1.0",
+    "@owlmeans/server-context": "^0.1.0",
+    "@owlmeans/storage-common": "^0.1.0",
+    "file-type": "^19.6.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.7.8",
+    "nodemon": "^3.1.7",
+    "typescript": "^5.6.3"
+  },
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/consts.ts

@@ -0,0 +1,5 @@
+import { supportedMimeTypes as mimeTypes } from 'file-type'
+
+export const DEFAULT_ALIAS = 's3-storage'
+
+export const supportedMimeTypes = [...mimeTypes]

package/src/helper.ts

@@ -0,0 +1,22 @@
+import type { StoredFile, StoredFileWithData } from '@owlmeans/storage-common'
+
+export const stripData = <
+  Input extends StoredFileWithData,
+  Output extends StoredFile
+>(file: Input): Output => {
+  const intermediate: Input = { ...file }
+
+  if (intermediate.format) {
+    delete intermediate.format
+  }
+
+  intermediate.instances = Object.fromEntries(
+    Object.entries(file.instances).map(([key, instance]) => [key, {
+      size: instance.size,
+      alias: instance.alias,
+      url: instance.url,
+    }])
+  )
+
+  return JSON.parse(JSON.stringify(intermediate)) as Output
+}

package/src/index.ts

@@ -0,0 +1,5 @@
+
+export type * from './types.js'
+export * from './consts.js'
+export * from './helper.js'
+export * from './resource.js'

package/src/resource.ts

@@ -0,0 +1,93 @@
+import { appendContextual } from '@owlmeans/context'
+import { DEFAULT_ALIAS } from './consts.js'
+import type { Config, Context, StorageResource, StoredRecord } from './types.js'
+import type { GetterOptions } from '@owlmeans/resource'
+import { FilePropertyError, FileStreamError, FileTypeError, StorageApiError } from '@owlmeans/storage-common'
+import { S3Client, PutObjectCommand } from '@aws-sdk/client-s3'
+import { ResilientError } from '@owlmeans/error'
+import { fileTypeFromBuffer } from 'file-type'
+
+type Getter = string | GetterOptions
+
+export const createStorageResource = (alias: string = DEFAULT_ALIAS, configKey?: string) => {
+  configKey ??= alias
+
+  const resource = appendContextual<StorageResource>(alias, {
+    create: async <Type extends StoredRecord>(record: Partial<Type>, _opts?: Getter) => {
+      if (record.stream == null) {
+        throw new FileStreamError('no')
+      }
+      if (record.size == null) {
+        throw new FilePropertyError('size')
+      }
+
+
+      // @TODO Do something here - it would be fixed if we do not convert
+      // multipart into buffer by means integrated into fastify
+      const buffers = await record.stream.toArray()
+      const buffer = buffers[0]
+      const type = await fileTypeFromBuffer(buffer)
+
+      if (type?.mime !== record.type) {
+        throw new FileTypeError('mime-mismatch')
+      }
+
+      const context = resource.assertCtx() as Context
+
+      const config = context.cfg.storageBuckets[configKey]
+      const [keyId, keySecret] = config.apiKey.split(':')
+      const [bucket, ...parts] = config.url.split('.')
+
+      // @TODO Abstract it some way and make the upload multipart
+      try {
+        const client = new S3Client({
+          region: 'eu-central-1',
+          endpoint: `https://${parts.join('.')}`,
+          credentials: {
+            accessKeyId: keyId,
+            secretAccessKey: keySecret,
+          }
+        })
+
+        const result = await client.send(new PutObjectCommand({
+          ACL: 'public-read',
+          Bucket: bucket,
+          Body: Buffer.concat(buffers),
+          Key: `${config.basePrefix}/${record.prefix}`,
+          ContentLength: record.size,
+          ContentDisposition: 'inline',
+          ContentType: record.type,
+        }))
+
+        if (result.$metadata.httpStatusCode !== 200) {
+          throw new StorageApiError('code')
+        }
+
+        record.url = `https://${config.url}/${config.basePrefix}/${record.prefix}`
+        delete record.stream
+
+        client.destroy()
+      } catch (e) {
+        if (e instanceof ResilientError) {
+          throw e
+        }
+        console.error(e)
+        throw new StorageApiError()
+      }
+
+      return record as Type
+    }
+  })
+
+  return resource
+}
+
+export const appendStorageResource = <C extends Config, T extends Context<C>>(
+  ctx: T, alias: string = DEFAULT_ALIAS, configKey?: string
+): T => {
+  const resource = createStorageResource(alias, configKey)
+
+  ctx.registerResource(resource)
+
+  return ctx
+}

package/src/types.ts

@@ -0,0 +1,31 @@
+import type { Resource, ResourceRecord } from '@owlmeans/resource'
+import type { StoredFileFormat } from '@owlmeans/storage-common'
+import type { ServerConfig, ServerContext } from '@owlmeans/server-context'
+import type { Readable } from 'stream'
+
+export interface StoredRecord extends ResourceRecord {
+  url?: string
+  size?: number
+  prefix: string
+  stream?: Readable
+  format?: StoredFileFormat
+  type?: string,
+  bytes?: Uint8Array
+  base64?: string
+}
+
+export interface StoredConfigAppend {
+  storageBuckets: { [key: string]: StorageConfig }
+}
+
+export interface StorageConfig {
+  url: string
+  apiKey: string
+  basePrefix: string
+}
+
+export interface StorageResource extends Resource<StoredRecord> {
+}
+
+export interface Config extends ServerConfig, StoredConfigAppend { }
+export interface Context<C extends Config = Config> extends ServerContext<C> { }

package/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": [
+    "../tsconfig.default.json",
+  ],
+  "compilerOptions": {
+    "rootDir": "./src/", /* Specify the root folder within your source files. */
+    "outDir": "./build/", /* Specify an output folder for all emitted files. */
+    "moduleResolution": "Bundler",
+  },
+  "exclude": [
+    "./dist/**/*",
+    "./build/**/*",
+    "./*.ts"
+  ]
+}

package/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["./src/consts.ts","./src/helper.ts","./src/index.ts","./src/model.ts","./src/resource.ts","./src/types.ts"],"version":"5.6.3"}