@quatrain/storage-s3 1.1.14 → 1.1.15

package/LICENSE.md

@@ -0,0 +1,15 @@
+# LICENSE UPDATE NOTICE
+
+As of 01/01/2026, Quatrain Core is licensed under the **GNU Affero General Public License v3.0 (AGPL v3)**.
+Previous versions remain under the MIT License.
+
+## Why AGPL?
+
+We believe in open collaboration for the development ecosystem. The AGPL ensures that any modification or deployment of this BaaS stack, including over a network, benefits the entire community.
+
+## Commercial Services & Enterprise Usage
+
+We provide official deployment services, technical training, and certification for Quatrain Core.
+For organizations requiring a non-copyleft license (commercial license) or custom proprietary integrations, please contact the copyright holder: **Quatrain Technologies**.
+
+Copyright © 2024-2026 Quatrain Technologies. All Rights Reserved.

package/README.md

@@ -1 +1,26 @@
-# Quatrain Amazon Storage Adapter
+# @quatrain/storage-s3
+
+A storage adapter for AWS S3 and other S3-compatible services like MinIO or DigitalOcean Spaces.
+
+## Features
+
+-  Implements the `@quatrain/storage` abstract adapter.
+-  Works with any S3-compatible object storage provider.
+-  Leverages the official AWS SDK for JavaScript (`@aws-sdk/client-s3`).
+-  Supports multipart uploads for large files.
+
+## Installation
+
+```bash
+npm install @quatrain/storage-s3 @aws-sdk/client-s3
+```
+
+## Usage
+
+```typescript
+import { Storage } from '@quatrain/storage';
+import { S3StorageAdapter } from '@quatrain/storage-s3';
+
+const adapter = new S3StorageAdapter({ config: { region: 'us-east-1', credentials: { ... } } });
+Storage.addAdapter(adapter, 'default', true);
+```

package/package.json

@@ -1,41 +1,39 @@
 {
-  "name": "@quatrain/storage-s3",
-  "version": "1.1.14",
-  "description": "Storage adapter for S3 compatible services",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
-  "files": [
-    "lib/",
-    "README.md"
-  ],
-  "author": "Quatrain Développement SAS <developers@quatrain.com>",
-  "license": "MIT",
-  "devDependencies": {
-    "@tsconfig/recommended": "^1.0.1",
-    "@types/jest": "^27.0.3",
-    "@types/node": "^22.10.1",
-    "jest": "^27.4.7",
-    "jest-node-exports-resolver": "^1.1.6",
-    "trace-unhandled": "^2.0.1",
-    "ts-jest": "^27.1.2",
-    "ts-node": "^10.4.0",
-    "typescript": "^5.1.5"
-  },
-  "dependencies": {
-    "@aws-sdk/client-s3": "^3.337.0",
-    "@aws-sdk/s3-request-presigner": "^3.342.0",
-    "@quatrain/storage": "^1.1.16",
-    "fs-extra": "^11.2.0"
-  },
-  "scripts": {
-    "test-ci": "jest --runInBand",
-    "build": "tsc",
-    "wbuild": "tsc --watch",
-    "bump-to": "yarn version",
-    "hash": "node ../../bin/hashFolder.js",
-    "hash:persist": "yarn hash  > .hash_latest.txt",
-    "hash:compare": "yarn hash > .hash_newest.txt && cmp -s .hash_latest.txt .hash_newest.txt",
-    "publish": "yarn hash:compare || yarn publish:process",
-    "publish:process": "yarn version patch && yarn build && yarn npm publish --access public && yarn hash:persist"
-  }
-}
+   "name": "@quatrain/storage-s3",
+   "version": "1.1.15",
+   "description": "Storage adapter for S3 compatible services",
+   "main": "lib/index.js",
+   "types": "lib/index.d.ts",
+   "bun": "src/index.ts",
+   "files": [
+      "LICENSE.md",
+      "src/",
+      "lib/",
+      "README.md"
+   ],
+   "author": "Quatrain Développement SAS <developers@quatrain.com>",
+   "license": "AGPL-3.0-only",
+   "devDependencies": {
+      "@tsconfig/recommended": "^1.0.1",
+      "@types/jest": "^27.0.3",
+      "@types/node": "^22.10.1",
+      "jest": "^30.2.0",
+      "jest-node-exports-resolver": "^1.1.6",
+      "trace-unhandled": "^2.0.1",
+      "ts-jest": "^27.1.2",
+      "ts-node": "^10.4.0",
+      "typescript": "^5.1.5"
+   },
+   "dependencies": {
+      "@aws-sdk/client-s3": "^3.337.0",
+      "@aws-sdk/s3-request-presigner": "^3.342.0",
+      "@quatrain/storage": "^1.1.24",
+      "fs-extra": "^11.2.0"
+   },
+   "scripts": {
+      "test-ci": "jest --runInBand",
+      "build": "tsc",
+      "wbuild": "tsc --watch",
+      "bump-to": "yarn version"
+   }
+}

package/src/S3StorageAdapter.ts

@@ -0,0 +1,242 @@
+import {
+   AbstractStorageAdapter,
+   Storage,
+   FileType,
+   FileResponseLinkType,
+   StorageParameters,
+   DownloadFileMetaType,
+} from '@quatrain/storage'
+import { Readable, Stream } from 'stream'
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner'
+import { createWriteStream } from 'fs'
+import {
+   S3Client,
+   PutObjectCommand,
+   GetObjectCommand,
+   DeleteObjectCommand,
+   CopyObjectCommand,
+   HeadObjectCommand,
+   ListBucketsCommand,
+} from '@aws-sdk/client-s3'
+
+export class S3StorageAdapter extends AbstractStorageAdapter {
+   protected _client: S3Client
+
+   constructor(params: StorageParameters) {
+      super(params)
+
+      const config = {
+         forcePathStyle: true,
+         region: this._params.config.region,
+         endpoint: this._params.config.endpoint,
+         credentials: {
+            accessKeyId: this._params.config.accesskey,
+            secretAccessKey: this._params.config.secret,
+         },
+      }
+
+      this._client = new S3Client(config)
+
+      Storage.info(
+         `AWS Storage Adapter initialized in ${
+            this._params.config.endpoint || this._params.config.region
+         }`
+      )
+   }
+
+   async test(): Promise<boolean> {
+      try {
+         const command = new ListBucketsCommand()
+         const res = await this._client.send(command)
+         //Storage.info(`S3 Buckets: ${JSON.stringify(res.Buckets)}`)
+         return true
+      } catch (err) {
+         Storage.error(`Failed to connect to S3: ${(err as Error).message}`)
+         return false
+      }
+   }
+
+   getDriver() {
+      return this._client
+   }
+
+   async streamToBuffer(stream: Stream): Promise<Buffer> {
+      return new Promise<Buffer>((resolve, reject) => {
+         const _buf: any[] = []
+
+         stream.on('data', (chunk) => _buf.push(chunk))
+         stream.on('end', () => resolve(Buffer.concat(_buf)))
+         stream.on('error', (err) => reject(err))
+      })
+   }
+
+   async create(file: FileType, stream: Readable): Promise<FileType> {
+      try {
+         const input = {
+            Bucket: file.bucket || this._params.config.bucket,
+            Key: file.ref,
+            Body: await this.streamToBuffer(stream),
+            ContentType: file.contentType,
+         }
+         Storage.debug(`Uploading ${file.ref} to ${file.bucket}`)
+
+         const command = new PutObjectCommand(input)
+         await this._client.send(command)
+
+         return file
+      } catch (err) {
+         Storage.error(
+            `Failed to upload file ${file.ref} to ${file.bucket}: ${
+               (err as Error).message
+            }`
+         )
+         throw new Error(
+            `Failed to upload file ${file.ref} to ${file.bucket}: ${
+               (err as Error).message
+            }`
+         )
+      }
+   }
+
+   async copy(file: FileType, destFile: FileType) {
+      Storage.debug(
+         `Copying file ${file.bucket}/${file.ref} to ${file.bucket}/${destFile.ref}`
+      )
+      const command = new CopyObjectCommand({
+         CopySource: encodeURI(`${file.bucket}/${file.ref}`),
+         Bucket: file.bucket,
+         Key: encodeURI(destFile.ref),
+      })
+
+      try {
+         await this._client.send(command)
+      } catch (err) {
+         console.error(err)
+      }
+   }
+
+   /**
+    * Move file to given destination
+    * There is no native command in AWS SDK for this, we need to copy then delete source media
+    * @param file
+    * @param destFile
+    * @returns
+    */
+   async move(file: FileType, destFile: FileType): Promise<FileType> {
+      try {
+         Storage.debug(
+            `Moving file ${file.bucket}/${file.ref} to ${file.bucket}/${destFile.ref}`
+         )
+         await this.copy(file, destFile)
+         await this.delete(file)
+      } catch (err) {
+         Storage.error(
+            `Failed to move file from ${file.ref} to ${destFile.ref}: ${
+               (err as Error).message
+            }`
+         )
+         console.log(err)
+      }
+
+      return destFile
+   }
+
+   async getUrl(file: FileType, expiresIn = 3600) {
+      const command = new GetObjectCommand({
+         Bucket: file.bucket,
+         Key: encodeURI(file.ref),
+      })
+      Storage.debug(`Creating public url for ${file.bucket}/${file.ref}`)
+      const url = await getSignedUrl(this._client, command, { expiresIn })
+      return { url, expiresIn }
+   }
+
+   async delete(file: FileType) {
+      Storage.debug(`Deleting file ${file.bucket}/${file.ref}`)
+      const command = new DeleteObjectCommand({
+         Bucket: file.bucket,
+         Key: file.ref,
+      })
+
+      await this._client?.send(command)
+      Storage.info(`Object ${file.ref} successfully deleted`)
+
+      return true
+   }
+
+   async getReadable(file: FileType): Promise<Readable> {
+      Storage.debug(`GET Readable for ${file.ref}`)
+      const command = new GetObjectCommand({
+         Bucket: file.bucket || this._params.config.bucket,
+         Key: file.ref,
+      })
+      const item = await this._client?.send(command)
+      const ByteArray: any = await item?.Body?.transformToByteArray()
+      const buffer = Buffer.from(ByteArray, 'base64')
+      const readable = new Readable()
+      readable.push(buffer)
+      readable.push(null)
+
+      return readable
+   }
+
+   async getMetaData(file: FileType): Promise<FileType> {
+      const command = new HeadObjectCommand({
+         Bucket: file.bucket,
+         Key: file.ref,
+      })
+      const item = await this._client.send(command)
+      const meta = {
+         ...file,
+         contentType: item.ContentType,
+         size: item.ContentLength,
+         lastModified: item.LastModified,
+      }
+
+      return meta
+   }
+
+   async stream(file: FileType, res: any) {
+      const command = new GetObjectCommand({
+         Bucket: file.bucket,
+         Key: file.ref,
+      })
+      const item = await this._client.send(command)
+      const ByteArray: any = await item.Body?.transformToByteArray()
+      const buffer = Buffer.from(ByteArray, 'base64')
+      const readable = new Readable()
+      readable.push(buffer)
+      readable.push(null)
+
+      return readable.pipe(res)
+   }
+
+   async download(file: FileType, meta: DownloadFileMetaType) {
+      const stream: Readable = await this.getReadable(file)
+      await new Promise((res) =>
+         stream.pipe(createWriteStream(meta.path)).on('close', res)
+      )
+
+      return meta.path
+   }
+
+   async getUploadUrl(
+      file: FileType,
+      expiresIn = 3600
+   ): Promise<FileResponseLinkType> {
+      const command = new PutObjectCommand({
+         Bucket: file.bucket || this._params.config.bucket,
+         Key: file.ref,
+         ContentType: file.contentType,
+      })
+
+      const url = await getSignedUrl(this._client, command, { expiresIn })
+
+      return {
+         url,
+         method: 'PUT',
+         accept: file.contentType || 'application/octet-stream',
+         expiresIn,
+      }
+   }
+}

package/src/index.ts

@@ -0,0 +1,3 @@
+import { S3StorageAdapter } from './S3StorageAdapter'
+
+export { S3StorageAdapter }