@studiocms/s3-storage 0.0.0-beta.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present StudioCMS - withstudiocms (https://github.com/withstudiocms)
+
+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,97 @@
+# @studiocms/s3-storage Plugin
+
+## Usage
+
+Add this plugin in your StudioCMS config. (`studiocms.config.mjs`)
+
+```ts
+import { defineStudioCMSConfig } from 'studiocms/config';
+import s3Storage from '@studiocms/s3-storage';
+
+export default defineStudioCMSConfig({
+    // other options here
+    storageManager: s3Storage()
+});
+```
+
+## Required Environment variables
+
+```env
+# ============================================
+# CONFIGURATION FOR DIFFERENT PROVIDERS
+# ============================================
+
+# -------------------- AWS S3 --------------------
+CMS_S3_PROVIDER=AWS
+CMS_S3_REGION=us-east-1
+CMS_S3_ENDPOINT=  # Leave empty for AWS
+CMS_S3_ACCESS_KEY_ID=your_access_key
+CMS_S3_SECRET_ACCESS_KEY=your_secret_key
+CMS_S3_BUCKET_NAME=your_bucket_name
+CMS_S3_FORCE_PATH_STYLE=false
+CMS_S3_PUBLIC_ENDPOINT=  # Optional: Custom public endpoint for accessing files
+
+# ------------ Cloudflare R2 --------------------
+# CMS_S3_PROVIDER=Cloudflare R2
+# CMS_S3_REGION=auto
+# CMS_S3_ENDPOINT=https://your-account-id.r2.cloudflarestorage.com
+# CMS_S3_ACCESS_KEY_ID=your_r2_access_key
+# CMS_S3_SECRET_ACCESS_KEY=your_r2_secret_key
+# CMS_S3_BUCKET_NAME=your_bucket_name
+# CMS_S3_FORCE_PATH_STYLE=false
+# CMS_S3_PUBLIC_ENDPOINT=  # Optional: Custom public endpoint for accessing files
+
+# ---------- DigitalOcean Spaces ----------------
+# CMS_S3_PROVIDER=DigitalOcean Spaces
+# CMS_S3_REGION=nyc3
+# CMS_S3_ENDPOINT=https://nyc3.digitaloceanspaces.com
+# CMS_S3_ACCESS_KEY_ID=your_spaces_key
+# CMS_S3_SECRET_ACCESS_KEY=your_spaces_secret
+# CMS_S3_BUCKET_NAME=your_space_name
+# CMS_S3_FORCE_PATH_STYLE=false
+# CMS_S3_PUBLIC_ENDPOINT=  # Optional: Custom public endpoint for accessing files
+
+# ------------- Backblaze B2 --------------------
+# CMS_S3_PROVIDER=Backblaze B2
+# CMS_S3_REGION=us-west-004
+# CMS_S3_ENDPOINT=https://s3.us-west-004.backblazeb2.com
+# CMS_S3_ACCESS_KEY_ID=your_b2_key_id
+# CMS_S3_SECRET_ACCESS_KEY=your_b2_application_key
+# CMS_S3_BUCKET_NAME=your_bucket_name
+# CMS_S3_FORCE_PATH_STYLE=false
+# CMS_S3_PUBLIC_ENDPOINT=  # Optional: Custom public endpoint for accessing files
+
+# --------------- MinIO -------------------------
+# CMS_S3_PROVIDER=MinIO
+# CMS_S3_REGION=us-east-1
+# CMS_S3_ENDPOINT=http://localhost:9000
+# CMS_S3_ACCESS_KEY_ID=minioadmin
+# CMS_S3_SECRET_ACCESS_KEY=minioadmin
+# CMS_S3_BUCKET_NAME=your_bucket_name
+# CMS_S3_FORCE_PATH_STYLE=true  # Required for MinIO
+# CMS_S3_PUBLIC_ENDPOINT=  # Optional: Custom public endpoint for accessing files
+
+# ------------- Wasabi --------------------------
+# CMS_S3_PROVIDER=Wasabi
+# CMS_S3_REGION=us-east-1
+# CMS_S3_ENDPOINT=https://s3.us-east-1.wasabisys.com
+# CMS_S3_ACCESS_KEY_ID=your_wasabi_key
+# CMS_S3_SECRET_ACCESS_KEY=your_wasabi_secret
+# CMS_S3_BUCKET_NAME=your_bucket_name
+# CMS_S3_FORCE_PATH_STYLE=false
+# CMS_S3_PUBLIC_ENDPOINT=  # Optional: Custom public endpoint for accessing files
+
+# ---------- Linode Object Storage --------------
+# CMS_S3_PROVIDER=Linode
+# CMS_S3_REGION=us-east-1
+# CMS_S3_ENDPOINT=https://us-east-1.linodeobjects.com
+# CMS_S3_ACCESS_KEY_ID=your_linode_key
+# CMS_S3_SECRET_ACCESS_KEY=your_linode_secret
+# CMS_S3_BUCKET_NAME=your_bucket_name
+# CMS_S3_FORCE_PATH_STYLE=false
+# CMS_S3_PUBLIC_ENDPOINT=  # Optional: Custom public endpoint for accessing files
+```
+
+## License
+
+[MIT Licensed](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * These triple-slash directives defines dependencies to various declaration files that will be
+ * loaded when a user imports the StudioCMS plugin in their Astro configuration file. These
+ * directives must be first at the top of the file and can only be preceded by this comment.
+ */
+import { type StudioCMSStorageManager } from 'studiocms/plugins';
+/**
+ * Creates and configures a StudioCMS S3 Storage Manager plugin.
+ *
+ * This function initializes the S3 storage integration for StudioCMS by defining
+ * a storage manager plugin with the necessary configuration and hooks.
+ *
+ * @returns {StudioCMSStorageManager} A configured storage manager instance that integrates
+ * S3 storage capabilities with StudioCMS.
+ *
+ * @remarks
+ * The storage manager registers a hook that sets up the S3 storage manager by resolving
+ * the path to the storage manager implementation file. It requires StudioCMS version
+ * 0.1.0-beta.31 or higher.
+ *
+ * @example
+ * ```typescript
+ * import { studiocmsS3Storage } from '@studiocms/s3-storage';
+ *
+ * const s3Storage = studiocmsS3Storage();
+ * ```
+ */
+export declare function studiocmsS3Storage(): StudioCMSStorageManager;
+export default studiocmsS3Storage;

package/dist/index.js

@@ -0,0 +1,24 @@
+import { createResolver } from "astro-integration-kit";
+import { defineStorageManager } from "studiocms/plugins";
+function studiocmsS3Storage() {
+  const { resolve } = createResolver(import.meta.url);
+  const packageIdentifier = "@studiocms/s3-storage";
+  return defineStorageManager({
+    identifier: packageIdentifier,
+    name: "StudioCMS S3 Storage",
+    studiocmsMinimumVersion: "0.1.0-beta.31",
+    hooks: {
+      "studiocms:storage-manager": ({ setStorageManager, logger }) => {
+        logger.info("StudioCMS S3 Storage initialized.");
+        setStorageManager({
+          managerPath: resolve("./s3-storage-manager.js")
+        });
+      }
+    }
+  });
+}
+var index_default = studiocmsS3Storage;
+export {
+  index_default as default,
+  studiocmsS3Storage
+};

package/dist/s3-storage-manager.d.ts

@@ -0,0 +1,41 @@
+import type { AuthorizationType, ContextDriverDefinition, StorageAPIEndpointFn, StorageApiBuilderDefinition, UrlMappingServiceDefinition } from 'studiocms/storage-manager/definitions';
+/**
+ * S3-compatible storage API service that provides endpoints for managing files in S3-compatible storage.
+ *
+ * Implements the StorageApiBuilderDefinition interface to handle various storage operations including
+ * file uploads, downloads, deletions, renames, and URL mapping management.
+ *
+ * @template C - The context type used by the underlying driver
+ * @template R - The response type returned by the driver
+ *
+ * @remarks
+ * This service supports the following operations through POST requests:
+ * - `resolveUrl`: Resolve a file identifier to its URL metadata
+ * - `publicUrl`: Generate and register a public URL for a file
+ * - `upload`: Generate a presigned URL for uploading files
+ * - `list`: List objects in the bucket with optional prefix filtering
+ * - `delete`: Delete a file and its URL mapping
+ * - `rename`: Rename/move a file and update its URL mapping
+ * - `download`: Generate a presigned URL for downloading files
+ * - `cleanup`: Remove expired URL mappings
+ * - `mappings`: Retrieve all URL mappings (debugging)
+ * - `test`: Test the S3 connection
+ *
+ * PUT requests are used for direct file uploads with the file key specified in the `x-storage-key` header.
+ *
+ * Most operations require authorization except for `resolveUrl` and `publicUrl` which are publicly accessible.
+ *
+ * @example
+ * ```typescript
+ * const service = new S3ApiService(driver, urlMappingService);
+ * const postEndpoint = service.getPOST('locals');
+ * const putEndpoint = service.getPUT('locals');
+ * ```
+ */
+export default class S3ApiService<C, R> implements StorageApiBuilderDefinition<C, R> {
+    driver: ContextDriverDefinition<C, R>;
+    urlMappingService: UrlMappingServiceDefinition;
+    constructor(driver: ContextDriverDefinition<C, R>, urlMappingService: UrlMappingServiceDefinition);
+    getPOST(type?: AuthorizationType): StorageAPIEndpointFn<C, R>;
+    getPUT(type?: AuthorizationType): StorageAPIEndpointFn<C, R>;
+}

package/dist/s3-storage-manager.js

@@ -0,0 +1,247 @@
+import {
+  CopyObjectCommand,
+  DeleteObjectCommand,
+  GetObjectCommand,
+  ListObjectsV2Command,
+  PutObjectCommand,
+  S3Client
+} from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { Config, ConfigProvider, Effect, Redacted } from "effect";
+const s3ClientBuilder = Effect.gen(function* () {
+  const [
+    // With default values for optional config
+    region,
+    endpoint,
+    forcePathStyle,
+    provider,
+    // Redacted config values
+    accessKeyId,
+    secretAccessKey,
+    // Required config values
+    bucketName,
+    publicEndpoint
+  ] = yield* Effect.all([
+    Config.withDefault(Config.string("REGION"), "auto"),
+    Config.withDefault(Config.string("ENDPOINT"), void 0),
+    Config.withDefault(Config.boolean("FORCE_PATH_STYLE"), false),
+    Config.withDefault(Config.string("PROVIDER"), "Unknown"),
+    Config.redacted("ACCESS_KEY_ID"),
+    Config.redacted("SECRET_ACCESS_KEY"),
+    Config.string("BUCKET_NAME"),
+    Config.string("PUBLIC_ENDPOINT")
+  ]);
+  const credentials = {
+    accessKeyId: Redacted.value(accessKeyId),
+    secretAccessKey: Redacted.value(secretAccessKey)
+  };
+  const client = new S3Client({
+    region,
+    endpoint,
+    credentials,
+    forcePathStyle
+  });
+  return {
+    client,
+    bucketName,
+    publicEndpoint,
+    provider
+  };
+}).pipe(Effect.withConfigProvider(ConfigProvider.fromEnv().pipe(ConfigProvider.nested("CMS_S3"))));
+let s3ClientInterface = null;
+const getS3Client = async () => {
+  if (!s3ClientInterface) {
+    s3ClientInterface = await Effect.runPromise(s3ClientBuilder);
+  }
+  return s3ClientInterface;
+};
+const generateUrlMetadata = ({ publicEndpoint, bucketName, client }) => async function generateUrlMetadata2(key) {
+  if (publicEndpoint) {
+    const publicUrl = publicEndpoint.endsWith("/") ? `${publicEndpoint}${key}` : `${publicEndpoint}/${key}`;
+    return { url: publicUrl, isPermanent: true };
+  }
+  const command = new GetObjectCommand({
+    Bucket: bucketName,
+    Key: key
+  });
+  const SevenDaysInSeconds = 7 * 24 * 60 * 60;
+  const inSevenDays = /* @__PURE__ */ new Date();
+  const url = await getSignedUrl(client, command, { expiresIn: SevenDaysInSeconds });
+  inSevenDays.setSeconds(inSevenDays.getSeconds() + SevenDaysInSeconds);
+  return { url, isPermanent: false, expiresAt: inSevenDays.getTime() };
+};
+class S3ApiService {
+  driver;
+  urlMappingService;
+  constructor(driver, urlMappingService) {
+    this.driver = driver;
+    this.urlMappingService = urlMappingService;
+  }
+  getPOST(type) {
+    return this.driver.handleEndpoint(async ({ getJson, isAuthorized }) => {
+      const jsonBody = await getJson();
+      const s3Interface = await getS3Client();
+      const { client: s3Client, bucketName: BUCKET_NAME, provider } = s3Interface;
+      const metaGenerator = generateUrlMetadata(s3Interface);
+      const authRequiredActions = [
+        "upload",
+        "delete",
+        "rename",
+        "cleanup",
+        "mappings",
+        "test",
+        "list"
+      ];
+      if (authRequiredActions.includes(jsonBody.action) && !isAuthorized(type)) {
+        return { data: { error: "Unauthorized" }, status: 401 };
+      }
+      switch (jsonBody.action) {
+        case "resolveUrl": {
+          const metadata = await this.urlMappingService.resolve(jsonBody.identifier, metaGenerator);
+          return { data: metadata, status: 200 };
+        }
+        case "publicUrl": {
+          const metadata = await metaGenerator(jsonBody.key);
+          const mappingIdentifier = this.urlMappingService.createIdentifier(jsonBody.key);
+          await this.urlMappingService.register(mappingIdentifier, metadata);
+          return {
+            data: {
+              ...metadata,
+              identifier: mappingIdentifier
+            },
+            status: 200
+          };
+        }
+        case "upload": {
+          const command = new PutObjectCommand({
+            Bucket: BUCKET_NAME,
+            Key: jsonBody.key,
+            ContentType: jsonBody.contentType
+          });
+          const url = await getSignedUrl(s3Client, command, { expiresIn: 3600 });
+          return { data: { url, key: jsonBody.key }, status: 200 };
+        }
+        case "list": {
+          const command = new ListObjectsV2Command({
+            Bucket: BUCKET_NAME,
+            Prefix: jsonBody.prefix || jsonBody.key || ""
+          });
+          const response = await s3Client.send(command);
+          const files = response.Contents?.map((item) => ({
+            key: item.Key,
+            size: item.Size,
+            lastModified: item.LastModified
+          })) || [];
+          return { data: { files }, status: 200 };
+        }
+        case "delete": {
+          const command = new DeleteObjectCommand({
+            Bucket: BUCKET_NAME,
+            Key: jsonBody.key
+          });
+          await s3Client.send(command);
+          const mappingIdentifier = this.urlMappingService.createIdentifier(jsonBody.key);
+          await this.urlMappingService.delete(mappingIdentifier);
+          return { data: { success: true }, status: 200 };
+        }
+        case "rename": {
+          if (!jsonBody.newKey) {
+            return { data: { error: "newKey is required for rename action" }, status: 400 };
+          }
+          const copyCommand = new CopyObjectCommand({
+            Bucket: BUCKET_NAME,
+            CopySource: `${BUCKET_NAME}/${jsonBody.key}`,
+            Key: jsonBody.newKey
+          });
+          await s3Client.send(copyCommand);
+          const deleteCommand = new DeleteObjectCommand({
+            Bucket: BUCKET_NAME,
+            Key: jsonBody.key
+          });
+          await s3Client.send(deleteCommand);
+          const oldMappingIdentifier = this.urlMappingService.createIdentifier(jsonBody.key);
+          await this.urlMappingService.delete(oldMappingIdentifier);
+          const newMappingIdentifier = this.urlMappingService.createIdentifier(jsonBody.newKey);
+          const urlMetadata = await metaGenerator(jsonBody.newKey);
+          await this.urlMappingService.register(newMappingIdentifier, urlMetadata);
+          return { data: { success: true, newKey: jsonBody.newKey }, status: 200 };
+        }
+        case "download": {
+          const command = new GetObjectCommand({
+            Bucket: BUCKET_NAME,
+            Key: jsonBody.key
+          });
+          const url = await getSignedUrl(s3Client, command, { expiresIn: 3600 });
+          return { data: { url }, status: 200 };
+        }
+        case "cleanup": {
+          const deletedCount = await this.urlMappingService.cleanup();
+          return { data: { deletedCount }, status: 200 };
+        }
+        case "mappings": {
+          const mappings = await this.urlMappingService.getAll();
+          return { data: { mappings }, status: 200 };
+        }
+        case "test": {
+          try {
+            const command = new ListObjectsV2Command({
+              Bucket: BUCKET_NAME,
+              MaxKeys: 1
+            });
+            await s3Client.send(command);
+            return {
+              data: {
+                success: true,
+                message: "Successfully connected to S3-compatible storage",
+                provider
+              },
+              status: 200
+            };
+          } catch (error) {
+            return {
+              data: {
+                success: false,
+                error: error instanceof Error ? error.message : "Connection failed"
+              },
+              status: 500
+            };
+          }
+        }
+        default:
+          return { data: { error: "Invalid action" }, status: 400 };
+      }
+    });
+  }
+  getPUT(type) {
+    return this.driver.handleEndpoint(async ({ getArrayBuffer, getHeader, isAuthorized }) => {
+      if (!isAuthorized(type)) {
+        return { data: { error: "Unauthorized" }, status: 401 };
+      }
+      const s3Interface = await getS3Client();
+      const { client: s3Client, bucketName: BUCKET_NAME } = s3Interface;
+      try {
+        const contentType = getHeader("Content-Type") || "application/octet-stream";
+        const key = getHeader("x-storage-key");
+        if (!key) {
+          return { data: { error: "Missing x-storage-key header" }, status: 400 };
+        }
+        const fileData = await getArrayBuffer();
+        const command = new PutObjectCommand({
+          Bucket: BUCKET_NAME,
+          Key: key,
+          Body: new Uint8Array(fileData),
+          ContentType: contentType
+        });
+        await s3Client.send(command);
+        console.log(`Successfully uploaded file to S3: ${key}`);
+        return { data: { message: "File uploaded successfully", key }, status: 200 };
+      } catch (error) {
+        console.error("S3 PUT Error:", error);
+        return { data: { error: error.message }, status: 500 };
+      }
+    });
+  }
+}
+export {
+  S3ApiService as default
+};

package/package.json

@@ -1,14 +1,70 @@
 {
   "name": "@studiocms/s3-storage",
-  "version": "0.0.0-beta.0",
-  "description": "",
-  "publishConfig": {
-    "access": "public"
+  "version": "0.1.1",
+  "description": "Add S3 Storage Support into your StudioCMS project.",
+  "author": {
+    "name": "withstudiocms",
+    "url": "https://studiocms.dev"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/withstudiocms/studiocms.git",
+    "directory": "packages/@studiocms/s3-storage"
   },
-  "keywords": [],
-  "author": "",
+  "contributors": [
+    "Adammatthiesen",
+    "jdtjenkins",
+    "dreyfus92",
+    "code.spirit"
+  ],
   "license": "MIT",
+  "keywords": [
+    "astro",
+    "astrocms",
+    "astrodb",
+    "astrostudio",
+    "astro-studio",
+    "astro-studiocms",
+    "cms",
+    "studiocms",
+    "studiocms-storage-manager"
+  ],
+  "homepage": "https://studiocms.dev",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "type": "module",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.958.0",
+    "@aws-sdk/s3-request-presigner": "^3.958.0",
+    "astro-integration-kit": "^0.19.1"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0"
+  },
+  "peerDependencies": {
+    "astro": "^5.12.9",
+    "effect": "^3.19.14",
+    "vite": "^6.3.4",
+    "studiocms": "^0.1.1"
+  },
   "scripts": {
-    "pre": "pnpm publish --tag beta"
+    "build": "buildkit build 'src/**/*.{ts,astro,css,json,png}'",
+    "dev": "buildkit dev 'src/**/*.{ts,astro,css,json,png}'",
+    "typecheck": "tspc -p tsconfig.tspc.json",
+    "effect-check": "pnpm effect-language-service diagnostics --project tsconfig.tspc.json",
+    "ci:effect-check": "pnpm effect-check --format github-actions",
+    "test": "vitest"
   }
 }