@opensaas/stack-storage-s3 0.1.1

package/.turbo/turbo-build.log

@@ -0,0 +1,4 @@
+
+> @opensaas/stack-storage-s3@0.1.1 build /home/runner/work/stack/stack/packages/storage-s3
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,9 @@
+# @opensaas/stack-storage-s3
+
+## 0.1.1
+
+### Patch Changes
+
+- 045c071: Add field and image upload
+- Updated dependencies [045c071]
+  - @opensaas/stack-storage@0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OpenSaas Stack Contributors
+
+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,171 @@
+# @opensaas/stack-storage-s3
+
+AWS S3 storage provider for OpenSaas Stack file uploads.
+
+## Installation
+
+```bash
+pnpm add @opensaas/stack-storage @opensaas/stack-storage-s3
+```
+
+## Usage
+
+```typescript
+// opensaas.config.ts
+import { config, list } from '@opensaas/stack-core'
+import { s3Storage } from '@opensaas/stack-storage-s3'
+import { image } from '@opensaas/stack-storage/fields'
+
+export default config({
+  storage: {
+    avatars: s3Storage({
+      bucket: 'my-avatars',
+      region: 'us-east-1',
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+    }),
+  },
+  lists: {
+    User: list({
+      fields: {
+        avatar: image({ storage: 'avatars' }),
+      },
+    }),
+  },
+})
+```
+
+## Configuration Options
+
+```typescript
+s3Storage({
+  // Required
+  bucket: string                    // S3 bucket name
+  region: string                    // AWS region (e.g., 'us-east-1')
+
+  // Optional - Authentication
+  accessKeyId?: string              // AWS access key (or use IAM role)
+  secretAccessKey?: string          // AWS secret key (or use IAM role)
+
+  // Optional - S3-compatible services
+  endpoint?: string                 // Custom endpoint (e.g., 'https://s3.backblazeb2.com')
+  forcePathStyle?: boolean          // Force path-style URLs (required for some services)
+
+  // Optional - Storage options
+  pathPrefix?: string               // Prefix for all files (e.g., 'uploads/')
+  generateUniqueFilenames?: boolean // Generate unique filenames (default: true)
+  acl?: string                      // ACL for uploaded files (default: 'private')
+
+  // Optional - Public URLs
+  customDomain?: string             // Custom domain for public URLs (e.g., 'https://cdn.example.com')
+})
+```
+
+## Examples
+
+### Standard AWS S3
+
+```typescript
+avatars: s3Storage({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+  secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+  acl: 'public-read',
+})
+```
+
+### With IAM Role (No Keys)
+
+```typescript
+avatars: s3Storage({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  // No accessKeyId/secretAccessKey - uses IAM role
+})
+```
+
+### With CloudFront CDN
+
+```typescript
+avatars: s3Storage({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  customDomain: 'https://d123456789.cloudfront.net',
+})
+```
+
+### Backblaze B2
+
+```typescript
+files: s3Storage({
+  bucket: 'my-bucket',
+  region: 'us-west-000',
+  endpoint: 'https://s3.us-west-000.backblazeb2.com',
+  forcePathStyle: true,
+  accessKeyId: process.env.B2_KEY_ID,
+  secretAccessKey: process.env.B2_APPLICATION_KEY,
+})
+```
+
+### MinIO (Self-Hosted)
+
+```typescript
+files: s3Storage({
+  bucket: 'my-bucket',
+  region: 'us-east-1',
+  endpoint: 'http://localhost:9000',
+  forcePathStyle: true,
+  accessKeyId: 'minioadmin',
+  secretAccessKey: 'minioadmin',
+})
+```
+
+### DigitalOcean Spaces
+
+```typescript
+files: s3Storage({
+  bucket: 'my-space',
+  region: 'nyc3',
+  endpoint: 'https://nyc3.digitaloceanspaces.com',
+  forcePathStyle: false,
+  accessKeyId: process.env.DO_SPACES_KEY,
+  secretAccessKey: process.env.DO_SPACES_SECRET,
+  customDomain: 'https://my-space.nyc3.cdn.digitaloceanspaces.com',
+})
+```
+
+## ACL Options
+
+- `'private'` - Only bucket owner has access (default)
+- `'public-read'` - Public read access
+- `'public-read-write'` - Public read/write access
+- `'authenticated-read'` - Authenticated AWS users have read access
+
+## Signed URLs
+
+The S3 provider supports signed URLs for private files:
+
+```typescript
+import { createStorageProvider } from '@opensaas/stack-storage/runtime'
+
+const provider = createStorageProvider(config, 'avatars')
+
+// Get signed URL valid for 1 hour
+const signedUrl = await provider.getSignedUrl('filename.jpg', 3600)
+```
+
+## Environment Variables
+
+Recommended setup:
+
+```env
+AWS_ACCESS_KEY_ID=your-access-key
+AWS_SECRET_ACCESS_KEY=your-secret-key
+AWS_REGION=us-east-1
+AWS_BUCKET=your-bucket
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+import type { StorageProvider, UploadOptions, UploadResult } from '@opensaas/stack-storage';
+/**
+ * Configuration for S3 storage
+ */
+export interface S3StorageConfig {
+    type: 's3';
+    /** S3 bucket name */
+    bucket: string;
+    /** AWS region */
+    region: string;
+    /** AWS access key ID (optional if using IAM role) */
+    accessKeyId?: string;
+    /** AWS secret access key (optional if using IAM role) */
+    secretAccessKey?: string;
+    /** Custom endpoint for S3-compatible services (e.g., MinIO, Backblaze) */
+    endpoint?: string;
+    /** Force path style URLs (required for some S3-compatible services) */
+    forcePathStyle?: boolean;
+    /** Base path prefix for all uploaded files */
+    pathPrefix?: string;
+    /** Whether to generate unique filenames (default: true) */
+    generateUniqueFilenames?: boolean;
+    /** ACL for uploaded files (default: 'private') */
+    acl?: 'private' | 'public-read' | 'public-read-write' | 'authenticated-read';
+    /** Custom domain for public URLs (e.g., 'https://cdn.example.com') */
+    customDomain?: string;
+}
+/**
+ * AWS S3 storage provider
+ * Supports standard S3 and S3-compatible services
+ */
+export declare class S3StorageProvider implements StorageProvider {
+    private client;
+    private config;
+    constructor(config: S3StorageConfig);
+    /**
+     * Generates a unique filename if configured
+     */
+    private generateFilename;
+    /**
+     * Gets the full key for an object including path prefix
+     */
+    private getFullKey;
+    upload(file: Buffer | Uint8Array, filename: string, options?: UploadOptions): Promise<UploadResult>;
+    download(filename: string): Promise<Buffer>;
+    delete(filename: string): Promise<void>;
+    getUrl(filename: string): string;
+    getSignedUrl(filename: string, expiresIn?: number): Promise<string>;
+}
+/**
+ * Creates an S3 storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     avatars: s3Storage({
+ *       bucket: 'my-avatars',
+ *       region: 'us-east-1',
+ *       accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+ *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export declare function s3Storage(config: Omit<S3StorageConfig, 'type'>): S3StorageConfig;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAA;AAE3F;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAA;IACV,qBAAqB;IACrB,MAAM,EAAE,MAAM,CAAA;IACd,iBAAiB;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,0EAA0E;IAC1E,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,uEAAuE;IACvE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,8CAA8C;IAC9C,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,2DAA2D;IAC3D,uBAAuB,CAAC,EAAE,OAAO,CAAA;IACjC,kDAAkD;IAClD,GAAG,CAAC,EAAE,SAAS,GAAG,aAAa,GAAG,mBAAmB,GAAG,oBAAoB,CAAA;IAC5E,sEAAsE;IACtE,YAAY,CAAC,EAAE,MAAM,CAAA;CACtB;AAED;;;GAGG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACvD,OAAO,CAAC,MAAM,CAAU;IACxB,OAAO,CAAC,MAAM,CAAiB;gBAEnB,MAAM,EAAE,eAAe;IAkBnC;;OAEG;IACH,OAAO,CAAC,gBAAgB;IAWxB;;OAEG;IACH,OAAO,CAAC,UAAU;IAOZ,MAAM,CACV,IAAI,EAAE,MAAM,GAAG,UAAU,EACzB,QAAQ,EAAE,MAAM,EAChB,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,CAAC;IA6BlB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAyB3C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAW7C,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAkB1B,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,GAAE,MAAa,GAAG,OAAO,CAAC,MAAM,CAAC;CAUhF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,eAAe,EAAE,MAAM,CAAC,GAAG,eAAe,CAOhF"}

package/dist/index.js

@@ -0,0 +1,145 @@
+import { S3Client, PutObjectCommand, GetObjectCommand, DeleteObjectCommand, } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { randomBytes } from 'node:crypto';
+/**
+ * AWS S3 storage provider
+ * Supports standard S3 and S3-compatible services
+ */
+export class S3StorageProvider {
+    client;
+    config;
+    constructor(config) {
+        this.config = config;
+        // Create S3 client
+        this.client = new S3Client({
+            region: config.region,
+            credentials: config.accessKeyId && config.secretAccessKey
+                ? {
+                    accessKeyId: config.accessKeyId,
+                    secretAccessKey: config.secretAccessKey,
+                }
+                : undefined,
+            endpoint: config.endpoint,
+            forcePathStyle: config.forcePathStyle,
+        });
+    }
+    /**
+     * Generates a unique filename if configured
+     */
+    generateFilename(originalFilename) {
+        if (this.config.generateUniqueFilenames === false) {
+            return originalFilename;
+        }
+        const ext = originalFilename.substring(originalFilename.lastIndexOf('.'));
+        const uniqueId = randomBytes(16).toString('hex');
+        const timestamp = Date.now();
+        return `${timestamp}-${uniqueId}${ext}`;
+    }
+    /**
+     * Gets the full key for an object including path prefix
+     */
+    getFullKey(filename) {
+        if (this.config.pathPrefix) {
+            return `${this.config.pathPrefix}/${filename}`;
+        }
+        return filename;
+    }
+    async upload(file, filename, options) {
+        const generatedFilename = this.generateFilename(filename);
+        const key = this.getFullKey(generatedFilename);
+        // Upload to S3
+        const command = new PutObjectCommand({
+            Bucket: this.config.bucket,
+            Key: key,
+            Body: file,
+            ContentType: options?.contentType,
+            Metadata: options?.metadata,
+            ACL: this.config.acl || 'private',
+            CacheControl: options?.cacheControl,
+        });
+        await this.client.send(command);
+        // Generate URL
+        const url = this.getUrl(generatedFilename);
+        return {
+            filename: generatedFilename,
+            url,
+            size: file.length,
+            contentType: options?.contentType || 'application/octet-stream',
+            metadata: options?.metadata,
+        };
+    }
+    async download(filename) {
+        const key = this.getFullKey(filename);
+        const command = new GetObjectCommand({
+            Bucket: this.config.bucket,
+            Key: key,
+        });
+        const response = await this.client.send(command);
+        if (!response.Body) {
+            throw new Error(`File not found: ${filename}`);
+        }
+        // Convert stream to buffer
+        const chunks = [];
+        const stream = response.Body;
+        for await (const chunk of stream) {
+            chunks.push(chunk);
+        }
+        return Buffer.concat(chunks);
+    }
+    async delete(filename) {
+        const key = this.getFullKey(filename);
+        const command = new DeleteObjectCommand({
+            Bucket: this.config.bucket,
+            Key: key,
+        });
+        await this.client.send(command);
+    }
+    getUrl(filename) {
+        const key = this.getFullKey(filename);
+        // Use custom domain if configured
+        if (this.config.customDomain) {
+            return `${this.config.customDomain}/${key}`;
+        }
+        // Use standard S3 URL
+        if (this.config.endpoint) {
+            // Custom endpoint (S3-compatible services)
+            return `${this.config.endpoint}/${this.config.bucket}/${key}`;
+        }
+        // Standard AWS S3 URL
+        return `https://${this.config.bucket}.s3.${this.config.region}.amazonaws.com/${key}`;
+    }
+    async getSignedUrl(filename, expiresIn = 3600) {
+        const key = this.getFullKey(filename);
+        const command = new GetObjectCommand({
+            Bucket: this.config.bucket,
+            Key: key,
+        });
+        return await getSignedUrl(this.client, command, { expiresIn });
+    }
+}
+/**
+ * Creates an S3 storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     avatars: s3Storage({
+ *       bucket: 'my-avatars',
+ *       region: 'us-east-1',
+ *       accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+ *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function s3Storage(config) {
+    return {
+        type: 's3',
+        generateUniqueFilenames: true,
+        acl: 'private',
+        ...config,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

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

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@opensaas/stack-storage-s3",
+  "version": "0.1.1",
+  "description": "AWS S3 storage provider for OpenSaas Stack file uploads",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.709.0",
+    "@aws-sdk/s3-request-presigner": "^3.709.0",
+    "@opensaas/stack-storage": "0.1.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "@vitest/coverage-v8": "^4.0.5",
+    "typescript": "^5.7.3",
+    "vitest": "^4.0.5"
+  },
+  "peerDependencies": {
+    "@opensaas/stack-storage": "0.1.1"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage"
+  }
+}

package/src/index.ts

@@ -0,0 +1,211 @@
+import {
+  S3Client,
+  PutObjectCommand,
+  GetObjectCommand,
+  DeleteObjectCommand,
+} from '@aws-sdk/client-s3'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import { randomBytes } from 'node:crypto'
+import type { StorageProvider, UploadOptions, UploadResult } from '@opensaas/stack-storage'
+
+/**
+ * Configuration for S3 storage
+ */
+export interface S3StorageConfig {
+  type: 's3'
+  /** S3 bucket name */
+  bucket: string
+  /** AWS region */
+  region: string
+  /** AWS access key ID (optional if using IAM role) */
+  accessKeyId?: string
+  /** AWS secret access key (optional if using IAM role) */
+  secretAccessKey?: string
+  /** Custom endpoint for S3-compatible services (e.g., MinIO, Backblaze) */
+  endpoint?: string
+  /** Force path style URLs (required for some S3-compatible services) */
+  forcePathStyle?: boolean
+  /** Base path prefix for all uploaded files */
+  pathPrefix?: string
+  /** Whether to generate unique filenames (default: true) */
+  generateUniqueFilenames?: boolean
+  /** ACL for uploaded files (default: 'private') */
+  acl?: 'private' | 'public-read' | 'public-read-write' | 'authenticated-read'
+  /** Custom domain for public URLs (e.g., 'https://cdn.example.com') */
+  customDomain?: string
+}
+
+/**
+ * AWS S3 storage provider
+ * Supports standard S3 and S3-compatible services
+ */
+export class S3StorageProvider implements StorageProvider {
+  private client: S3Client
+  private config: S3StorageConfig
+
+  constructor(config: S3StorageConfig) {
+    this.config = config
+
+    // Create S3 client
+    this.client = new S3Client({
+      region: config.region,
+      credentials:
+        config.accessKeyId && config.secretAccessKey
+          ? {
+              accessKeyId: config.accessKeyId,
+              secretAccessKey: config.secretAccessKey,
+            }
+          : undefined,
+      endpoint: config.endpoint,
+      forcePathStyle: config.forcePathStyle,
+    })
+  }
+
+  /**
+   * Generates a unique filename if configured
+   */
+  private generateFilename(originalFilename: string): string {
+    if (this.config.generateUniqueFilenames === false) {
+      return originalFilename
+    }
+
+    const ext = originalFilename.substring(originalFilename.lastIndexOf('.'))
+    const uniqueId = randomBytes(16).toString('hex')
+    const timestamp = Date.now()
+    return `${timestamp}-${uniqueId}${ext}`
+  }
+
+  /**
+   * Gets the full key for an object including path prefix
+   */
+  private getFullKey(filename: string): string {
+    if (this.config.pathPrefix) {
+      return `${this.config.pathPrefix}/${filename}`
+    }
+    return filename
+  }
+
+  async upload(
+    file: Buffer | Uint8Array,
+    filename: string,
+    options?: UploadOptions,
+  ): Promise<UploadResult> {
+    const generatedFilename = this.generateFilename(filename)
+    const key = this.getFullKey(generatedFilename)
+
+    // Upload to S3
+    const command = new PutObjectCommand({
+      Bucket: this.config.bucket,
+      Key: key,
+      Body: file,
+      ContentType: options?.contentType,
+      Metadata: options?.metadata,
+      ACL: this.config.acl || 'private',
+      CacheControl: options?.cacheControl,
+    })
+
+    await this.client.send(command)
+
+    // Generate URL
+    const url = this.getUrl(generatedFilename)
+
+    return {
+      filename: generatedFilename,
+      url,
+      size: file.length,
+      contentType: options?.contentType || 'application/octet-stream',
+      metadata: options?.metadata,
+    }
+  }
+
+  async download(filename: string): Promise<Buffer> {
+    const key = this.getFullKey(filename)
+
+    const command = new GetObjectCommand({
+      Bucket: this.config.bucket,
+      Key: key,
+    })
+
+    const response = await this.client.send(command)
+
+    if (!response.Body) {
+      throw new Error(`File not found: ${filename}`)
+    }
+
+    // Convert stream to buffer
+    const chunks: Uint8Array[] = []
+    const stream = response.Body as AsyncIterable<Uint8Array>
+
+    for await (const chunk of stream) {
+      chunks.push(chunk)
+    }
+
+    return Buffer.concat(chunks)
+  }
+
+  async delete(filename: string): Promise<void> {
+    const key = this.getFullKey(filename)
+
+    const command = new DeleteObjectCommand({
+      Bucket: this.config.bucket,
+      Key: key,
+    })
+
+    await this.client.send(command)
+  }
+
+  getUrl(filename: string): string {
+    const key = this.getFullKey(filename)
+
+    // Use custom domain if configured
+    if (this.config.customDomain) {
+      return `${this.config.customDomain}/${key}`
+    }
+
+    // Use standard S3 URL
+    if (this.config.endpoint) {
+      // Custom endpoint (S3-compatible services)
+      return `${this.config.endpoint}/${this.config.bucket}/${key}`
+    }
+
+    // Standard AWS S3 URL
+    return `https://${this.config.bucket}.s3.${this.config.region}.amazonaws.com/${key}`
+  }
+
+  async getSignedUrl(filename: string, expiresIn: number = 3600): Promise<string> {
+    const key = this.getFullKey(filename)
+
+    const command = new GetObjectCommand({
+      Bucket: this.config.bucket,
+      Key: key,
+    })
+
+    return await getSignedUrl(this.client, command, { expiresIn })
+  }
+}
+
+/**
+ * Creates an S3 storage configuration
+ *
+ * @example
+ * ```typescript
+ * const config = config({
+ *   storage: {
+ *     avatars: s3Storage({
+ *       bucket: 'my-avatars',
+ *       region: 'us-east-1',
+ *       accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+ *       secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+ *     }),
+ *   },
+ * })
+ * ```
+ */
+export function s3Storage(config: Omit<S3StorageConfig, 'type'>): S3StorageConfig {
+  return {
+    type: 's3',
+    generateUniqueFilenames: true,
+    acl: 'private',
+    ...config,
+  }
+}