@flink-app/s3-plugin 0.12.1-alpha.9 → 0.13.1

package/CHANGELOG.md

@@ -0,0 +1,20 @@
+# @flink-app/s3-plugin
+
+## 0.13.1
+
+### Patch Changes
+
+-   Fixed invalid types and improve typescript error message during schema compilation
+-   Updated dependencies
+    -   @flink-app/flink@0.13.1
+
+## 0.13.0
+
+### Minor Changes
+
+-   Migrate to pnpm and streamlines build process.
+
+### Patch Changes
+
+-   Updated dependencies
+    -   @flink-app/flink@0.13.0

package/dist/index.js

@@ -35,8 +35,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");
@@ -79,6 +79,8 @@ var s3Plugin = function (options) {
         bucket: options.bucket,
         s3Acl: options.s3Acl,
         endpoint: options.endpoint,
+        signatureVersion: options.signatureVersion,
+        region: options.region,
     });
     return {
         id: "s3Plugin",

package/dist/s3Client.d.ts

@@ -1,5 +1,3 @@
-/// <reference types="node" />
-/// <reference types="node" />
 import AWS from "aws-sdk";
 import S3, { ManagedUpload, ObjectIdentifierList } from "aws-sdk/clients/s3";
 import { ListObjectResponse } from "./schemas/ListObjectsResponse";

package/dist/s3Client.js

@@ -9,8 +9,8 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
     });
 };
 var __generator = (this && this.__generator) || function (thisArg, body) {
-    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
-    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g = Object.create((typeof Iterator === "function" ? Iterator : Object).prototype);
+    return g.next = verb(0), g["throw"] = verb(1), g["return"] = verb(2), typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
     function verb(n) { return function (v) { return step([n, v]); }; }
     function step(op) {
         if (f) throw new TypeError("Generator is already executing.");
@@ -57,6 +57,8 @@ var S3Client = /** @class */ (function () {
             },
             // @ts-ignore
             endpoint: this.s3Endpoint ? new aws_sdk_1.default.Endpoint(this.s3Endpoint) : undefined,
+            signatureVersion: options.signatureVersion,
+            region: options.region,
         });
     }
     S3Client.prototype.checkIfExists = function (fileName) {

package/dist/schemas/s3ClientOptions.d.ts

@@ -4,4 +4,6 @@ export interface s3ClientOptions {
     bucket: string;
     s3Acl?: string;
     endpoint?: string;
+    region?: string;
+    signatureVersion?: string;
 }

package/dist/schemas/s3PluginOptions.d.ts

@@ -8,4 +8,6 @@ export interface s3PluginOptions {
     enableUpload: boolean;
     uploadUrl?: string;
     uploadPermissionRequired?: string;
+    signatureVersion?: string;
+    region?: string;
 }

package/package.json

@@ -1,34 +1,31 @@
 {
-    "name": "@flink-app/s3-plugin",
-    "version": "0.12.1-alpha.9",
-    "description": "Flink plugin to work with s3",
-    "scripts": {
-        "test": "echo \"Error: no test specified\"",
-        "prepare": "tsc"
-    },
-    "author": "johan@frost.se",
-    "publishConfig": {
-        "access": "public"
-    },
-    "license": "MIT",
-    "types": "dist/index.d.ts",
-    "main": "dist/index.js",
-    "dependencies": {
-        "@types/mime-types": "^2.1.1",
-        "aws-sdk": "^2.1117.0",
-        "express": "^4.17.1",
-        "express-fileupload": "^1.3.1",
-        "mime-types": "^2.1.35",
-        "node-color-log": "^5.3.1"
-    },
-    "devDependencies": {
-        "@flink-app/flink": "^0.12.1-alpha.9",
-        "@types/express": "4.17.13",
-        "@types/express-fileupload": "^1.2.2",
-        "@types/node": "22.13.10",
-        "@types/uuid": "^8.3.4",
-        "ts-node": "^9.1.1",
-        "typescript": "5.4.5"
-    },
-    "gitHead": "3007ad036607014176930446fde56203bde8d6f5"
-}
+  "name": "@flink-app/s3-plugin",
+  "version": "0.13.1",
+  "description": "Flink plugin to work with s3",
+  "author": "johan@frost.se",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "dependencies": {
+    "@types/mime-types": "^2.1.1",
+    "aws-sdk": "^2.1117.0",
+    "express-fileupload": "^1.3.1",
+    "mime-types": "^2.1.35",
+    "node-color-log": "^5.3.1",
+    "@flink-app/flink": "0.13.1"
+  },
+  "devDependencies": {
+    "@types/express-fileupload": "^1.2.2",
+    "@types/node": "22.13.10",
+    "@types/uuid": "^8.3.4"
+  },
+  "gitHead": "4243e3b3cd6d4e1ca001a61baa8436bf2bbe4113",
+  "scripts": {
+    "test": "echo \"Error: no test specified\"",
+    "build": "tsc",
+    "clean": "rimraf dist .flink"
+  }
+}

package/readme.md

@@ -1,57 +1,301 @@
-# Flink API Docs
+# S3 Plugin
 
-**WORK IN PROGRESS 👷‍♀️👷🏻‍♂️**
+A Flink plugin for AWS S3 integration, providing file storage, upload, and management operations. Works with AWS S3 and S3-compatible services.
 
-A FLINK plugin that lets you work with s3.
+## Installation
+
+```bash
+npm install @flink-app/s3-plugin
+```
 
 ## Usage
 
-Install plugin to your flink app project:
+Add and configure the plugin in your app startup:
 
+```typescript
+import { s3Plugin } from "@flink-app/s3-plugin";
+import { FlinkApp } from "@flink-app/flink";
+import AppContext from "./ApplicationContext";
+
+async function start() {
+    await new FlinkApp<AppContext>({
+        name: "My app",
+        plugins: [
+            s3Plugin({
+                accessKeyId: process.env.AWS_ACCESS_KEY_ID,
+                secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY,
+                bucket: "my-bucket-name",
+                region: "us-east-1",
+                s3Acl: "public-read",
+                enableUpload: true,
+                uploadUrl: "/file-upload",
+                maxFileSize: 10, // MB
+                uploadPermissionRequired: "authenticated",
+            }),
+        ],
+    }).start();
+}
 ```
-npm i -S @flink-app/s3-plugin
+
+Add the plugin context to your application context:
+
+```typescript
+import { s3PluginContext } from "@flink-app/s3-plugin";
+import { FlinkContext } from "@flink-app/flink";
+
+interface ApplicationContext extends FlinkContext<s3PluginContext> {
+    // your context here
+}
+
+export default ApplicationContext;
 ```
 
-Add and configure plugin in your app startup (probable the `index.ts` in root project):
+## Configuration Options
 
+```typescript
+interface s3PluginOptions {
+    accessKeyId: string;           // AWS access key ID (required)
+    secretAccessKey: string;       // AWS secret access key (required)
+    bucket: string;                // S3 bucket name (required)
+    s3Acl?: string;               // Access control list (e.g., "public-read", "private")
+    endpoint?: string;             // Custom S3 endpoint (for S3-compatible services)
+    signatureVersion?: string;     // AWS signature version
+    region?: string;               // AWS region (e.g., "us-east-1")
+    enableUpload: boolean;         // Enable file upload endpoint (required)
+    uploadUrl?: string;            // Custom upload endpoint path (default: "/file-upload")
+    maxFileSize?: number;          // Max file size in MB (default: 10)
+    uploadPermissionRequired?: string; // Permission required for uploads
+}
 ```
-import { s3Plugin } from "@flink-app/s3-plugin";
 
+## Built-in Upload Endpoint
 
-function start() {
-  new FlinkApp<AppContext>({
-    name: "My app",
-    plugins: [
-        // Register plugin
-        s3Plugin({
-                accessKeyId: "XXX",
-                secretAccessKey: "YYY",
-                bucket: "ZZZ",
-                s3Acl: "public-read",
-                enableUpload: true,
-        }),
-    ],
-  }).start();
+When `enableUpload` is set to `true`, the plugin registers a file upload endpoint:
+
+### POST /file-upload (or custom uploadUrl)
+
+Upload a file using multipart form data:
+
+```bash
+curl -X POST http://localhost:3333/file-upload?path=images/ \
+  -F "file=@photo.jpg" \
+  -H "Authorization: Bearer <token>"
+```
+
+**Query Parameters:**
+- `path` (optional): S3 path prefix for the uploaded file
+
+**Response:**
+```json
+{
+    "status": 200,
+    "data": {
+        "url": "https://my-bucket.s3.amazonaws.com/images/photo-1234567890.jpg"
+    }
 }
 ```
 
-Finally add the s3PluginContext to your `Ctx.ts`
+**Permission Protection:**
+Set `uploadPermissionRequired` to require authentication:
+```typescript
+s3Plugin({
+    // ...
+    enableUpload: true,
+    uploadPermissionRequired: "authenticated", // or any custom permission
+})
+```
+
+## S3Client API
+
+Access the S3 client from your handlers:
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import AppContext from "../ApplicationContext";
+
+const UploadFile: Handler<AppContext, UploadReq, UploadRes> = async ({ ctx, req }) => {
+    const s3Client = ctx.plugins.s3Plugin.s3Client;
+
+    // Your S3 operations here
+};
+```
+
+### Available Methods
+
+#### uploadFile(fileName, data, mime)
+Upload a file to S3.
+
+```typescript
+const url = await ctx.plugins.s3Plugin.s3Client.uploadFile(
+    "documents/report.pdf",
+    fileBuffer,
+    "application/pdf"
+);
 ```
-import { s3PluginContext } from "@flink-app/s3-plugin"
-export interface Ctx extends FlinkContext<s3PluginContext> {
 
+#### getObject(key)
+Retrieve a file from S3.
+
+```typescript
+const file = await ctx.plugins.s3Plugin.s3Client.getObject("documents/report.pdf");
+```
+
+#### getObjects()
+List all objects in the bucket.
+
+```typescript
+const objects = await ctx.plugins.s3Plugin.s3Client.getObjects();
+```
+
+#### deleteObject(file, version?)
+Delete a single object.
+
+```typescript
+await ctx.plugins.s3Plugin.s3Client.deleteObject("documents/old-report.pdf");
+```
+
+#### deleteObjects(files)
+Bulk delete multiple objects.
+
+```typescript
+await ctx.plugins.s3Plugin.s3Client.deleteObjects([
+    "file1.jpg",
+    "file2.jpg",
+    "file3.jpg",
+]);
+```
+
+#### getSignedUrl(key, expires)
+Generate a temporary signed URL for private objects.
+
+```typescript
+const signedUrl = await ctx.plugins.s3Plugin.s3Client.getSignedUrl(
+    "private/document.pdf",
+    3600 // expires in seconds
+);
+```
+
+#### checkIfExists(fileName)
+Check if a file exists in the bucket.
+
+```typescript
+const exists = await ctx.plugins.s3Plugin.s3Client.checkIfExists("documents/report.pdf");
+```
+
+## Complete Example
+
+```typescript
+import { Handler } from "@flink-app/flink";
+import AppContext from "../ApplicationContext";
+
+interface UploadDocumentReq {
+    fileName: string;
+    fileData: string; // base64 encoded
+    mimeType: string;
+}
+
+interface UploadDocumentRes {
+    url: string;
+    exists: boolean;
 }
+
+export const Route = {
+    path: "/document/upload",
+};
+
+const UploadDocument: Handler<AppContext, UploadDocumentReq, UploadDocumentRes> = async ({ ctx, req }) => {
+    const { fileName, fileData, mimeType } = req.body;
+    const s3Client = ctx.plugins.s3Plugin.s3Client;
+
+    // Check if file already exists
+    const exists = await s3Client.checkIfExists(fileName);
+
+    if (exists) {
+        return {
+            status: 409,
+            data: {
+                url: "",
+                exists: true,
+            },
+        };
+    }
+
+    // Upload file
+    const buffer = Buffer.from(fileData, "base64");
+    const url = await s3Client.uploadFile(fileName, buffer, mimeType);
+
+    return {
+        status: 200,
+        data: {
+            url,
+            exists: false,
+        },
+    };
+};
+
+export default UploadDocument;
 ```
 
+## S3-Compatible Services
 
+This plugin works with S3-compatible services like MinIO, DigitalOcean Spaces, etc.:
+
+```typescript
+s3Plugin({
+    accessKeyId: "your-key",
+    secretAccessKey: "your-secret",
+    bucket: "my-bucket",
+    endpoint: "https://nyc3.digitaloceanspaces.com", // Custom endpoint
+    region: "nyc3",
+    s3Acl: "public-read",
+    enableUpload: true,
+})
+```
+
+## Access Control Lists (ACL)
+
+Common ACL values:
+- `private`: Owner gets full control, no one else has access
+- `public-read`: Owner gets full control, public gets read access
+- `public-read-write`: Owner gets full control, public gets read/write access
+- `authenticated-read`: Owner gets full control, authenticated users get read access
+
+## Environment Variables
+
+Recommended setup using environment variables:
+
+```bash
+AWS_ACCESS_KEY_ID=your-access-key-id
+AWS_SECRET_ACCESS_KEY=your-secret-access-key
+AWS_REGION=us-east-1
+S3_BUCKET=my-bucket-name
+```
+
+```typescript
+s3Plugin({
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    bucket: process.env.S3_BUCKET!,
+    region: process.env.AWS_REGION,
+    s3Acl: "public-read",
+    enableUpload: true,
+})
+```
 
-## Using built in upload endpoint
-Set `enableUpload = true` to enable the /file-upload endpoint. 
-Post a multipart file upload to that endpoint to upload the file to S3. 
-Protect this route by specifying the required permission by specifying `uploadPermissionRequired` property to the required permission. Eg. `uploadPermissionRequired="authenticated"` setting. 
+## Features
 
+- ✅ AWS S3 integration
+- ✅ S3-compatible service support
+- ✅ Built-in file upload endpoint
+- ✅ Permission-based access control
+- ✅ Multipart file upload support
+- ✅ File size limits
+- ✅ Signed URL generation
+- ✅ Bulk operations
+- ✅ File existence checking
 
-## Using the s3Client
-From your handlers, access the s3Client by  `ctx.plugins.s3Plugin.s3Client`.
-You will find methods for upload, delete and so on.
+## Requirements
 
+- AWS account with S3 access (or S3-compatible service)
+- Valid AWS credentials (access key ID and secret access key)
+- S3 bucket created and accessible

package/src/index.ts

@@ -14,6 +14,8 @@ export const s3Plugin = (options: s3PluginOptions): FlinkPlugin => {
         bucket: options.bucket,
         s3Acl: options.s3Acl,
         endpoint: options.endpoint,
+        signatureVersion: options.signatureVersion,
+        region: options.region,
     });
 
     return {

package/src/s3Client.ts

@@ -29,6 +29,8 @@ class S3Client {
             },
             // @ts-ignore
             endpoint: this.s3Endpoint ? new AWS.Endpoint(this.s3Endpoint) : undefined,
+            signatureVersion: options.signatureVersion,
+            region: options.region,
         });
     }
 

package/src/schemas/s3ClientOptions.ts

@@ -4,4 +4,6 @@ export interface s3ClientOptions {
     bucket: string;
     s3Acl?: string;
     endpoint?: string;
+    region?: string;
+    signatureVersion?: string;
 }

package/src/schemas/s3PluginOptions.ts

@@ -8,4 +8,6 @@ export interface s3PluginOptions {
     enableUpload: boolean;
     uploadUrl?: string;
     uploadPermissionRequired?: string;
+    signatureVersion?: string;
+    region?: string;
 }

package/tsconfig.json

@@ -15,7 +15,7 @@
     "noEmit": false,
     "declaration": true,
     "experimentalDecorators": true,
-    "checkJs": true,
+    "checkJs": false,
     "outDir": "dist"
   },
   "include": ["./src/*"],