@geekmidas/storage 0.0.1

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "@geekmidas/storage",
+  "version": "0.0.1",
+  "private": false,
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    "./aws": {
+      "import": "./dist/aws.mjs",
+      "require": "./dist/aws.cjs",
+      "types": "./src/aws.ts"
+    },
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs",
+      "types": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "zod": "~3.25.67"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "~3.844.0",
+    "@aws-sdk/s3-presigned-post": "^3.844.0",
+    "@aws-sdk/s3-request-presigner": "~3.844.0"
+  },
+  "scripts": {}
+}

package/src/AmazonStorageClient.ts

@@ -0,0 +1,176 @@
+import {
+  GetObjectCommand,
+  ListObjectVersionsCommand,
+  PutObjectCommand,
+  S3Client,
+} from '@aws-sdk/client-s3';
+import { createPresignedPost } from '@aws-sdk/s3-presigned-post';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+
+import {
+  type DocumentVersion,
+  type File,
+  type GetUploadParams,
+  type GetUploadResponse,
+  type StorageClient,
+  StorageProvider,
+} from './StorageClient';
+
+export class AmazonStorageClient implements StorageClient {
+  readonly provider = StorageProvider.AWSS3;
+  static create(
+    options: AmazonStorageClientCreateOptions,
+  ): AmazonStorageClient {
+    const {
+      bucket,
+      region,
+      accessKeyId,
+      acl,
+      endpoint,
+      secretAccessKey,
+      forcePathStyle = false,
+    } = options;
+    const hasCredentials = accessKeyId && secretAccessKey;
+    const credentials = hasCredentials
+      ? { accessKeyId, secretAccessKey }
+      : undefined;
+
+    const client = new S3Client({
+      region,
+      credentials,
+      endpoint,
+      forcePathStyle,
+    });
+
+    return new AmazonStorageClient(client, bucket, acl);
+  }
+  constructor(
+    private readonly client: S3Client,
+    private readonly bucket: string,
+    private readonly acl = AmazonCannedAccessControlList.AuthenticatedRead,
+  ) {}
+
+  getVersionDownloadURL(file: File, versionId: string): Promise<string> {
+    const ResponseContentDisposition = file.name
+      ? `attachment; filename=${encodeURIComponent(file.name)}`
+      : undefined;
+
+    const command = new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: file.path,
+      ResponseContentDisposition,
+      VersionId: versionId,
+    });
+
+    return getSignedUrl(this.client, command, { expiresIn: 60 * 60 * 24 });
+  }
+
+  async getVersions(key: string): Promise<DocumentVersion[]> {
+    const command = new ListObjectVersionsCommand({
+      Bucket: this.bucket,
+      Prefix: key,
+    });
+
+    const { Versions = [] } = await this.client.send(command);
+
+    return Versions.map((version) => ({
+      id: version.VersionId || '',
+      createdAt: version.LastModified || new Date(),
+    }));
+  }
+
+  getDownloadURL(file: File, expiresIn = 60 * 60): Promise<string> {
+    const ResponseContentDisposition = file.name
+      ? `attachment; filename=${encodeURIComponent(file.name)}`
+      : undefined;
+
+    const command = new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: file.path,
+      ResponseContentDisposition,
+    });
+
+    return getSignedUrl(this.client, command, { expiresIn });
+  }
+
+  async getUploadURL(
+    params: GetUploadParams,
+    expiresIn = 60 * 60,
+  ): Promise<string> {
+    const command = new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: params.path,
+      ContentType: params.contentType,
+      ContentLength: params.contentLength,
+    });
+
+    return getSignedUrl(this.client, command, { expiresIn });
+  }
+
+  async getUpload(
+    params: GetUploadParams,
+    expiresIn = 5,
+  ): Promise<GetUploadResponse> {
+    const { path } = params;
+    const { fields: values, url } = await createPresignedPost(this.client, {
+      Expires: expiresIn * 60,
+      Bucket: this.bucket,
+      Fields: {
+        acl: this.acl,
+      },
+      Conditions: [
+        // content length restrictions: 0-1MB]
+        // ['content-length-range', 0, contentLength],
+        // specify content-type to be more generic- images only
+        // ['starts-with', '$Content-Type', 'image/'],
+        // ['starts-with', '$Content-Type', contentType],
+      ],
+      Key: path,
+    });
+
+    const keys = Object.keys(values);
+    const fields = keys.map((key) => ({ key, value: values[key] || '' }));
+
+    return { url, fields };
+  }
+
+  async upload(
+    key: string,
+    data: string | Buffer,
+    contentType: string,
+  ): Promise<void> {
+    const Body = typeof data === 'string' ? Buffer.from(data, 'base64') : data;
+
+    const params = {
+      Bucket: this.bucket,
+      Key: key,
+      Body,
+      ContentType: contentType,
+    };
+
+    const command = new PutObjectCommand(params);
+
+    await this.client.send(command);
+  }
+}
+
+export enum AmazonCannedAccessControlList {
+  AuthenticatedRead = 'authenticated-read',
+  Private = 'private',
+  PublicRead = 'public-read',
+  PublicReadWrite = 'public-read-write',
+  AwsExecRead = 'aws-exec-read',
+  BucketOwnerRead = 'bucket-owner-read',
+  BucketOwnerFullControl = 'bucket-owner-full-control',
+  LogDeliveryWrite = 'log-delivery-write',
+}
+
+interface AmazonStorageClientCreateOptions {
+  bucket: string;
+  region?: string;
+  acl?: AmazonCannedAccessControlList;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  endpoint?: string;
+  forcePathStyle?: boolean;
+}

package/src/StorageClient.ts

@@ -0,0 +1,89 @@
+export interface DocumentVersion {
+  id: string;
+  createdAt: Date;
+}
+
+export enum StorageProvider {
+  AWSS3 = 'geekimdas.toolbox.storage.aws.s3',
+  GCP = 'geekimdas.toolbox.storage.gcp',
+  AZURE = 'geekimdas.toolbox.storage.azure',
+}
+
+export interface StorageClient {
+  readonly provider: StorageProvider;
+  /**
+   * Get a URL to upload a file to.
+   *
+   * @param params - The parameters to get the upload URL for.
+   * @param expiresIn - The number of minutes the URL should be valid for.
+   * Defaults to 60 * 60 (1 hour).
+   * @returns A promise that resolves to the upload URL.
+   */
+  getUploadURL(params: GetUploadParams, expiresIn?: number): Promise<string>;
+
+  /**
+   * Get a URL to download a file from.
+   *
+   * @param file - The file to get the download URL for.
+   * @param expiresIn - The number of seconds the URL should be valid for.
+   * Defaults to 60 * 60 (1 hour).
+   * @returns A promise that resolves to the download URL.
+   */
+  getDownloadURL(file: File, expiresIn?: number): Promise<string>;
+  /**
+   * Get the versions for a key.
+   *
+   * @param key - The key to get the versions for.
+   */
+  getVersions(key: string): Promise<DocumentVersion[]>;
+
+  /**
+   * Get a URL to download a version of a file from.
+   *
+   * @param file - The file to get the download URL for.
+   * @param versionId - The version ID to get the download URL for.
+   */
+  getVersionDownloadURL(file: File, versionId: string): Promise<string>;
+  /**
+   *
+   * @param key - The key to upload the file to.
+   * @param data - The data to upload.
+   * @param contentType - The content type of the data.
+   */
+  upload(
+    key: string,
+    data: string | Buffer,
+    contentType: string,
+  ): Promise<void>;
+  /**
+   * Get a URL to upload a file to.
+   *
+   * @param params - The parameters to get the upload URL for.
+   * @param expiresIn - The number of minutes the URL should be valid for.
+   */
+  getUpload(
+    params: GetUploadParams,
+    expiresIn?: number,
+  ): Promise<GetUploadResponse>;
+}
+
+export interface GetUploadParams {
+  path: string;
+  contentType: string;
+  contentLength: number;
+}
+
+export type UploadField = {
+  key: string;
+  value: string;
+};
+
+export type GetUploadResponse = {
+  url: string;
+  fields: UploadField[];
+};
+
+export interface File {
+  name?: string;
+  path: string;
+}

package/src/__tests__/AmazonStorageClient.spec.ts

@@ -0,0 +1,327 @@
+import { S3Client } from '@aws-sdk/client-s3';
+import { beforeAll, describe, expect, it } from 'vitest';
+import {
+  AmazonCannedAccessControlList,
+  AmazonStorageClient,
+} from '../AmazonStorageClient';
+import { StorageProvider } from '../StorageClient';
+
+describe('AmazonStorageClient Integration Tests', () => {
+  let client: AmazonStorageClient;
+  const testBucket = 'geekmidas';
+  const testKey = 'test-files/test.txt';
+  const testContent = 'Hello, World!';
+  const testContentType = 'text/plain';
+
+  beforeAll(async () => {
+    // Create storage client pointing to MinIO
+    client = AmazonStorageClient.create({
+      bucket: testBucket,
+      region: 'us-east-1',
+      accessKeyId: 'geekmidas',
+      secretAccessKey: 'geekmidas',
+      endpoint: 'http://localhost:9000',
+      acl: AmazonCannedAccessControlList.PublicRead,
+      forcePathStyle: true,
+    });
+
+    // Wait for MinIO to be ready
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+  });
+
+  describe('provider property', () => {
+    it('should return AWS S3 provider', () => {
+      expect(client.provider).toBe(StorageProvider.AWSS3);
+    });
+  });
+
+  describe('upload and download workflow', () => {
+    it.skip('should upload a file directly and generate download URL', async () => {
+      // Upload file directly
+      await client.upload(testKey, testContent, testContentType);
+
+      // Generate download URL
+      const downloadUrl = await client.getDownloadURL({ path: testKey });
+
+      expect(downloadUrl).toMatch(
+        /^http:\/\/localhost:9000\/geekmidas\/test-files\/test\.txt/,
+      );
+      expect(downloadUrl).toContain('X-Amz-Algorithm=AWS4-HMAC-SHA256');
+      expect(downloadUrl).toContain('X-Amz-Credential=');
+      expect(downloadUrl).toContain('X-Amz-Date=');
+      expect(downloadUrl).toContain('X-Amz-SignedHeaders=');
+      expect(downloadUrl).toContain('X-Amz-Signature=');
+
+      // Verify file can be downloaded
+      const response = await fetch(downloadUrl);
+      expect(response.ok).toBe(true);
+
+      const downloadedContent = await response.text();
+      expect(downloadedContent).toBe(testContent);
+    });
+
+    it('should upload a file with filename and generate download URL with content disposition', async () => {
+      const keyWithName = 'test-files/named-file.txt';
+      const fileName = 'my-document.txt';
+
+      await client.upload(keyWithName, testContent, testContentType);
+
+      const downloadUrl = await client.getDownloadURL({
+        path: keyWithName,
+        name: fileName,
+      });
+
+      expect(downloadUrl).toContain(
+        'response-content-disposition=attachment%3B%20filename%3Dmy-document.txt',
+      );
+    });
+
+    it('should handle binary data upload', async () => {
+      const binaryKey = 'test-files/binary.bin';
+      const binaryData = Buffer.from([0x48, 0x65, 0x6c, 0x6c, 0x6f]); // "Hello" in bytes
+
+      await client.upload(binaryKey, binaryData, 'application/octet-stream');
+
+      const downloadUrl = await client.getDownloadURL({ path: binaryKey });
+      const response = await fetch(downloadUrl);
+      const downloadedBuffer = await response.arrayBuffer();
+
+      expect(new Uint8Array(downloadedBuffer)).toEqual(
+        new Uint8Array(binaryData),
+      );
+    });
+  });
+
+  describe('presigned upload URLs', () => {
+    it('should generate presigned PUT upload URL', async () => {
+      const uploadKey = 'test-files/presigned-upload.txt';
+      const uploadUrl = await client.getUploadURL({
+        path: uploadKey,
+        contentType: testContentType,
+        contentLength: testContent.length,
+      });
+
+      expect(uploadUrl).toMatch(
+        /^http:\/\/localhost:9000\/geekmidas\/test-files\/presigned-upload\.txt/,
+      );
+      expect(uploadUrl).toContain('X-Amz-Algorithm=AWS4-HMAC-SHA256');
+
+      // Test actual upload using the presigned URL
+      const uploadResponse = await fetch(uploadUrl, {
+        method: 'PUT',
+        headers: {
+          'Content-Type': testContentType,
+          'Content-Length': testContent.length.toString(),
+        },
+        body: testContent,
+      });
+
+      expect(uploadResponse.ok).toBe(true);
+
+      // Verify file was uploaded
+      const downloadUrl = await client.getDownloadURL({ path: uploadKey });
+      const downloadResponse = await fetch(downloadUrl);
+      const downloadedContent = await downloadResponse.text();
+      expect(downloadedContent).toBe(testContent);
+    });
+
+    it('should generate presigned POST upload with form fields', async () => {
+      const uploadKey = 'test-files/presigned-post.txt';
+      const uploadData = await client.getUpload({
+        path: uploadKey,
+        contentType: testContentType,
+        contentLength: testContent.length,
+      });
+
+      expect(uploadData.url).toBe('http://localhost:9000/geekmidas');
+      expect(uploadData.fields).toContainEqual({
+        key: 'key',
+        value: uploadKey,
+      });
+      expect(uploadData.fields).toContainEqual({
+        key: 'acl',
+        value: 'public-read',
+      });
+
+      // Test actual upload using the presigned POST
+      const formData = new FormData();
+      uploadData.fields.forEach(({ key, value }) => {
+        formData.append(key, value);
+      });
+      formData.append(
+        'file',
+        new Blob([testContent], { type: testContentType }),
+      );
+
+      const uploadResponse = await fetch(uploadData.url, {
+        method: 'POST',
+        body: formData,
+      });
+
+      expect(uploadResponse.ok).toBe(true);
+
+      // Verify file was uploaded
+      const downloadUrl = await client.getDownloadURL({ path: uploadKey });
+      const downloadResponse = await fetch(downloadUrl);
+      const downloadedContent = await downloadResponse.blob();
+      expect(downloadedContent).toEqual(
+        new Blob([testContent], { type: testContentType }),
+      );
+    });
+  });
+
+  describe('versioning', () => {
+    it('should handle file versions', async () => {
+      const versionKey = 'test-files/versioned.txt';
+      const content1 = 'Version 1';
+      const content2 = 'Version 2';
+
+      // Upload first version
+      await client.upload(versionKey, content1, testContentType);
+
+      // Upload second version
+      await client.upload(versionKey, content2, testContentType);
+
+      // Get versions - MinIO might not enable versioning by default
+      // This test verifies the method works even if versioning is not enabled
+      const versions = await client.getVersions(versionKey);
+      expect(Array.isArray(versions)).toBe(true);
+
+      // If versioning is enabled, we should have multiple versions
+      // If not, we should have at least the current version
+      if (versions.length > 0) {
+        expect(versions[0]).toHaveProperty('id');
+        expect(versions[0]).toHaveProperty('createdAt');
+        expect(versions[0].createdAt).toBeInstanceOf(Date);
+      }
+    });
+  });
+
+  describe('error handling', () => {
+    it('should handle download URL generation for non-existent files', async () => {
+      // This should not throw - presigned URLs can be generated for non-existent files
+      const downloadUrl = await client.getDownloadURL({
+        path: 'non-existent/file.txt',
+      });
+      expect(downloadUrl).toMatch(
+        /^http:\/\/localhost:9000\/geekmidas\/non-existent\/file\.txt/,
+      );
+
+      // But accessing the URL should return 404
+      const response = await fetch(downloadUrl);
+      expect(response.status).toBe(404);
+    });
+  });
+
+  describe('custom expiration times', () => {
+    it('should respect custom expiration for download URLs', async () => {
+      const key = 'test-files/expiration-test.txt';
+      await client.upload(key, testContent, testContentType);
+
+      const shortExpirationUrl = await client.getDownloadURL({ path: key }, 1); // 1 second
+      const longExpirationUrl = await client.getDownloadURL(
+        { path: key },
+        3600,
+      ); // 1 hour
+
+      expect(shortExpirationUrl).toContain('X-Amz-Expires=1');
+      expect(longExpirationUrl).toContain('X-Amz-Expires=3600');
+    });
+
+    it('should respect custom expiration for upload URLs', async () => {
+      const key = 'test-files/upload-expiration-test.txt';
+
+      const shortExpirationUrl = await client.getUploadURL(
+        {
+          path: key,
+          contentType: testContentType,
+          contentLength: testContent.length,
+        },
+        1,
+      ); // 1 second
+
+      const longExpirationUrl = await client.getUploadURL(
+        {
+          path: key,
+          contentType: testContentType,
+          contentLength: testContent.length,
+        },
+        3600,
+      ); // 1 hour
+
+      expect(shortExpirationUrl).toContain('X-Amz-Expires=1');
+      expect(longExpirationUrl).toContain('X-Amz-Expires=3600');
+    });
+  });
+
+  describe('factory method', () => {
+    it('should create client with minimal configuration', () => {
+      const minimalClient = AmazonStorageClient.create({
+        bucket: 'geekmidas',
+      });
+
+      expect(minimalClient).toBeInstanceOf(AmazonStorageClient);
+      expect(minimalClient.provider).toBe(StorageProvider.AWSS3);
+    });
+
+    it('should create client with full configuration', () => {
+      const fullClient = AmazonStorageClient.create({
+        bucket: 'geekmidas',
+        region: 'us-west-2',
+        accessKeyId: 'test-key',
+        secretAccessKey: 'test-secret',
+        endpoint: 'https://custom-s3.example.com',
+        acl: AmazonCannedAccessControlList.Private,
+      });
+
+      expect(fullClient).toBeInstanceOf(AmazonStorageClient);
+      expect(fullClient.provider).toBe(StorageProvider.AWSS3);
+    });
+  });
+
+  describe('different ACL configurations', () => {
+    it('should work with different ACL settings', async () => {
+      const privateClient = AmazonStorageClient.create({
+        bucket: testBucket,
+        region: 'us-east-1',
+        accessKeyId: 'minioadmin',
+        secretAccessKey: 'minioadmin',
+        endpoint: 'http://localhost:9000',
+        acl: AmazonCannedAccessControlList.Private,
+      });
+
+      const uploadData = await privateClient.getUpload({
+        path: 'test-files/private.txt',
+        contentType: testContentType,
+        contentLength: testContent.length,
+      });
+
+      expect(uploadData.fields).toContainEqual({
+        key: 'acl',
+        value: 'private',
+      });
+    });
+  });
+
+  describe('S3Client integration', () => {
+    it('should work with externally created S3Client', () => {
+      const s3Client = new S3Client({
+        region: 'us-east-1',
+        credentials: {
+          accessKeyId: 'minioadmin',
+          secretAccessKey: 'minioadmin',
+        },
+        endpoint: 'http://localhost:9000',
+      });
+
+      const storageClient = new AmazonStorageClient(
+        s3Client,
+        testBucket,
+        AmazonCannedAccessControlList.PublicRead,
+      );
+
+      expect(storageClient).toBeInstanceOf(AmazonStorageClient);
+      expect(storageClient.provider).toBe(StorageProvider.AWSS3);
+    });
+  });
+});

package/src/__tests__/StorageClient.spec.ts

@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { StorageProvider } from '../StorageClient';
+
+describe('StorageClient', () => {
+  describe('StorageProvider enum', () => {
+    it('should have correct provider values', () => {
+      expect(StorageProvider.AWSS3).toBe('geekimdas.toolbox.storage.aws.s3');
+      expect(StorageProvider.GCP).toBe('geekimdas.toolbox.storage.gcp');
+      expect(StorageProvider.AZURE).toBe('geekimdas.toolbox.storage.azure');
+    });
+
+    it('should have unique provider values', () => {
+      const values = Object.values(StorageProvider);
+      const uniqueValues = new Set(values);
+      expect(uniqueValues.size).toBe(values.length);
+    });
+  });
+
+  describe('interfaces', () => {
+    it('should define DocumentVersion interface correctly', () => {
+      // This is a compile-time test to ensure the interface exists
+      // and has the correct shape
+      const version: import('../StorageClient').DocumentVersion = {
+        id: 'test-id',
+        createdAt: new Date(),
+      };
+
+      expect(version.id).toBe('test-id');
+      expect(version.createdAt).toBeInstanceOf(Date);
+    });
+
+    it('should define File interface correctly', () => {
+      const file: import('../StorageClient').File = {
+        path: 'test/path.txt',
+      };
+
+      expect(file.path).toBe('test/path.txt');
+      expect(file.name).toBeUndefined();
+
+      const fileWithName: import('../StorageClient').File = {
+        path: 'test/path.txt',
+        name: 'display-name.txt',
+      };
+
+      expect(fileWithName.path).toBe('test/path.txt');
+      expect(fileWithName.name).toBe('display-name.txt');
+    });
+
+    it('should define GetUploadParams interface correctly', () => {
+      const params: import('../StorageClient').GetUploadParams = {
+        path: 'test/upload.txt',
+        contentType: 'text/plain',
+        contentLength: 100,
+      };
+
+      expect(params.path).toBe('test/upload.txt');
+      expect(params.contentType).toBe('text/plain');
+      expect(params.contentLength).toBe(100);
+    });
+
+    it('should define GetUploadResponse interface correctly', () => {
+      const response: import('../StorageClient').GetUploadResponse = {
+        url: 'https://example.com/upload',
+        fields: [
+          { key: 'key', value: 'test/path.txt' },
+          { key: 'acl', value: 'public-read' },
+        ],
+      };
+
+      expect(response.url).toBe('https://example.com/upload');
+      expect(response.fields).toHaveLength(2);
+      expect(response.fields[0]).toEqual({ key: 'key', value: 'test/path.txt' });
+      expect(response.fields[1]).toEqual({ key: 'acl', value: 'public-read' });
+    });
+
+    it('should define UploadField type correctly', () => {
+      const field: import('../StorageClient').UploadField = {
+        key: 'test-key',
+        value: 'test-value',
+      };
+
+      expect(field.key).toBe('test-key');
+      expect(field.value).toBe('test-value');
+    });
+  });
+});