cloud-service-kit 1.0.0

package/README.md

@@ -0,0 +1,200 @@
+# cloud-service-kit
+
+A modular cloud service toolkit for Node.js. Handles S3 media uploads, with support for more services (email, etc.) coming soon.
+
+## Installation
+
+```bash
+npm install cloud-service-kit
+```
+
+## Prerequisites
+
+- Node.js >= 18.0.0
+- AWS S3 bucket with access credentials
+
+## Quick Start
+
+```typescript
+import { S3MediaClient } from "cloud-service-kit";
+
+const s3 = new S3MediaClient({
+  aws: {
+    region: "us-east-1",
+    bucket: "your-bucket-name",
+    accessKey: "YOUR_AWS_ACCESS_KEY",
+    secretKey: "YOUR_AWS_SECRET_KEY",
+  },
+});
+
+// Upload image from a live URL
+const result = await s3.media.uploadFromUrl("https://example.com/photo.jpg", {
+  folder: "uploads",
+});
+
+// Upload from buffer (e.g. Express + multer)
+const result2 = await s3.media.uploadBuffer(fileBuffer, {
+  contentType: "image/jpeg",
+  folder: "user-uploads",
+});
+
+console.log(result.url); // Full S3 URL
+```
+
+## Setup
+
+### Using environment variables (recommended)
+
+```typescript
+import { S3MediaClient } from "cloud-service-kit";
+
+const s3 = new S3MediaClient({
+  aws: {
+    region: process.env.AWS_REGION!,
+    bucket: process.env.AWS_BUCKET!,
+    accessKey: process.env.AWS_ACCESS_KEY!,
+    secretKey: process.env.AWS_SECRET_KEY!,
+  },
+});
+```
+
+> Initialize once at app startup and reuse the instance throughout your application.
+
+---
+
+## Modules
+
+### Media Module
+
+Handles fetching images from URLs or accepting buffers and uploading them to AWS S3.
+
+#### `s3.media.uploadFromUrl(url, options?)`
+
+Fetches an image from a live URL and uploads it to S3.
+
+```typescript
+const result = await s3.media.uploadFromUrl("https://example.com/photo.jpg");
+```
+
+With options:
+
+```typescript
+const result = await s3.media.uploadFromUrl("https://example.com/photo.jpg", {
+  folder: "uploads",                // S3 folder prefix
+  key: "custom/path/photo.jpg",     // or provide a full custom key
+  contentType: "image/jpeg",        // override auto-detected content type
+});
+```
+
+**Parameters:**
+
+| Parameter             | Type     | Required | Description                                                  |
+| --------------------- | -------- | -------- | ------------------------------------------------------------ |
+| `url`                 | `string` | Yes      | The live URL to fetch the image from                         |
+| `options.key`         | `string` | No       | Custom S3 key. If omitted, a UUID-based key is auto-generated |
+| `options.folder`      | `string` | No       | S3 folder prefix (e.g. `"uploads"`). Ignored if `key` is set |
+| `options.contentType` | `string` | No       | MIME type override. Auto-detected from response headers      |
+
+---
+
+#### `s3.media.uploadBuffer(buffer, options?)`
+
+Uploads a Buffer directly to S3. Useful for file uploads via multer/express.
+
+```typescript
+// Example with Express + multer
+app.post("/upload", upload.single("image"), async (req, res) => {
+  const result = await s3.media.uploadBuffer(req.file.buffer, {
+    contentType: req.file.mimetype,
+    folder: "user-uploads",
+  });
+  res.json(result);
+});
+```
+
+**Parameters:**
+
+| Parameter             | Type     | Required | Description                                                  |
+| --------------------- | -------- | -------- | ------------------------------------------------------------ |
+| `buffer`              | `Buffer` | Yes      | The file buffer to upload                                    |
+| `options.key`         | `string` | No       | Custom S3 key. If omitted, a UUID-based key is auto-generated |
+| `options.folder`      | `string` | No       | S3 folder prefix. Ignored if `key` is set                    |
+| `options.contentType` | `string` | No       | MIME type. Defaults to `"application/octet-stream"`          |
+
+---
+
+#### Response Format
+
+Both methods return a `MediaUploadResponse`:
+
+```typescript
+{
+  key: "uploads/550e8400-e29b-41d4-a716-446655440000.jpg",
+  url: "https://your-bucket.s3.us-east-1.amazonaws.com/uploads/550e8400-e29b-41d4-a716-446655440000.jpg",
+  bucket: "your-bucket-name",
+  contentType: "image/jpeg",
+  size: 102400
+}
+```
+
+| Field         | Type     | Description                          |
+| ------------- | -------- | ------------------------------------ |
+| `key`         | `string` | The S3 object key                    |
+| `url`         | `string` | Full public S3 URL                   |
+| `bucket`      | `string` | S3 bucket name                       |
+| `contentType` | `string` | MIME content type of the file        |
+| `size`        | `number` | File size in bytes                   |
+
+---
+
+## Exports
+
+```typescript
+import {
+  S3MediaClient,        // Main S3 client class
+  S3MediaConfig,        // Configuration interface
+  AWSConfig,            // AWS credentials interface
+  MediaUploadOptions,   // Upload options
+  MediaUploadResponse,  // Upload response
+} from "cloud-service-kit";
+```
+
+## How It Works
+
+1. **Initialization** — `new S3MediaClient(config)` creates an internal S3 client using your AWS credentials.
+2. **Upload from URL** — `uploadFromUrl` uses native `fetch()` to download the image, auto-detects content type from response headers, generates a UUID-based S3 key (or uses your custom key), and uploads the buffer to S3.
+3. **Upload from Buffer** — `uploadBuffer` takes a raw Buffer (e.g. from multer) and uploads it directly to S3.
+4. **Key generation** — When no custom key is provided, a UUID is generated using `crypto.randomUUID()` and the file extension is resolved from the source URL or content type.
+
+## Upcoming Modules
+
+This toolkit is designed to be extended with more service modules:
+
+- **S3 Media** — Available now
+- **Email** — Coming soon
+- **More** — Additional cloud services planned
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run structure tests
+node test.js
+```
+
+## Publishing
+
+```bash
+npm login
+npm publish
+npm info cloud-service-kit
+```
+
+## License
+
+UNLICENSED

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { S3MediaClient } from "./s3-media-client";
+export { S3MediaConfig, AWSConfig } from "./types";
+export { MediaUploadOptions, MediaUploadResponse } from "./modules/media";

package/dist/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3MediaClient = void 0;
+var s3_media_client_1 = require("./s3-media-client");
+Object.defineProperty(exports, "S3MediaClient", { enumerable: true, get: function () { return s3_media_client_1.S3MediaClient; } });

package/dist/lib/s3.client.d.ts

@@ -0,0 +1,4 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { AWSConfig } from "../types";
+export declare function createS3Client(config: AWSConfig): S3Client;
+export declare function uploadToS3(client: S3Client, bucket: string, buffer: Buffer, key: string, contentType: string): Promise<string>;

package/dist/lib/s3.client.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createS3Client = createS3Client;
+exports.uploadToS3 = uploadToS3;
+const client_s3_1 = require("@aws-sdk/client-s3");
+function createS3Client(config) {
+    return new client_s3_1.S3Client({
+        region: config.region,
+        credentials: {
+            accessKeyId: config.accessKey,
+            secretAccessKey: config.secretKey,
+        },
+    });
+}
+async function uploadToS3(client, bucket, buffer, key, contentType) {
+    const command = new client_s3_1.PutObjectCommand({
+        Bucket: bucket,
+        Key: key,
+        Body: buffer,
+        ContentType: contentType,
+    });
+    await client.send(command);
+    return key;
+}

package/dist/modules/media/index.d.ts

@@ -0,0 +1,2 @@
+export { MediaModule } from "./media.module";
+export { MediaUploadOptions, MediaUploadResponse } from "./media.types";

package/dist/modules/media/index.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaModule = void 0;
+var media_module_1 = require("./media.module");
+Object.defineProperty(exports, "MediaModule", { enumerable: true, get: function () { return media_module_1.MediaModule; } });

package/dist/modules/media/media.module.d.ts

@@ -0,0 +1,19 @@
+import { S3Client } from "@aws-sdk/client-s3";
+import { AWSConfig } from "../../types";
+import { MediaUploadOptions, MediaUploadResponse } from "./media.types";
+export declare class MediaModule {
+    private s3Client;
+    private awsConfig;
+    constructor(s3Client: S3Client, awsConfig: AWSConfig);
+    /**
+     * Fetch an image from a live URL and upload it to S3.
+     */
+    uploadFromUrl(url: string, options?: MediaUploadOptions): Promise<MediaUploadResponse>;
+    /**
+     * Upload a buffer (e.g. from multer file upload) directly to S3.
+     */
+    uploadBuffer(buffer: Buffer, options?: MediaUploadOptions): Promise<MediaUploadResponse>;
+    private generateKey;
+    private resolveExtension;
+    private buildS3Url;
+}

package/dist/modules/media/media.module.js

@@ -0,0 +1,91 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MediaModule = void 0;
+const crypto_1 = __importDefault(require("crypto"));
+const path_1 = __importDefault(require("path"));
+const s3_client_1 = require("../../lib/s3.client");
+class MediaModule {
+    constructor(s3Client, awsConfig) {
+        this.s3Client = s3Client;
+        this.awsConfig = awsConfig;
+    }
+    /**
+     * Fetch an image from a live URL and upload it to S3.
+     */
+    async uploadFromUrl(url, options = {}) {
+        const response = await fetch(url);
+        if (!response.ok) {
+            throw new Error(`Failed to fetch image from URL: ${response.status} ${response.statusText}`);
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        const contentType = options.contentType ||
+            response.headers.get("content-type") ||
+            "application/octet-stream";
+        const key = options.key || this.generateKey(options.folder, url, contentType);
+        await (0, s3_client_1.uploadToS3)(this.s3Client, this.awsConfig.bucket, buffer, key, contentType);
+        return {
+            key,
+            url: this.buildS3Url(key),
+            bucket: this.awsConfig.bucket,
+            contentType,
+            size: buffer.length,
+        };
+    }
+    /**
+     * Upload a buffer (e.g. from multer file upload) directly to S3.
+     */
+    async uploadBuffer(buffer, options = {}) {
+        const contentType = options.contentType || "application/octet-stream";
+        const key = options.key || this.generateKey(options.folder, undefined, contentType);
+        await (0, s3_client_1.uploadToS3)(this.s3Client, this.awsConfig.bucket, buffer, key, contentType);
+        return {
+            key,
+            url: this.buildS3Url(key),
+            bucket: this.awsConfig.bucket,
+            contentType,
+            size: buffer.length,
+        };
+    }
+    generateKey(folder, sourceUrl, contentType) {
+        const uuid = crypto_1.default.randomUUID();
+        const ext = this.resolveExtension(sourceUrl, contentType);
+        const filename = `${uuid}${ext}`;
+        return folder ? `${folder}/${filename}` : filename;
+    }
+    resolveExtension(sourceUrl, contentType) {
+        // Try to get extension from the source URL
+        if (sourceUrl) {
+            try {
+                const pathname = new URL(sourceUrl).pathname;
+                const ext = path_1.default.extname(pathname);
+                if (ext)
+                    return ext;
+            }
+            catch {
+                // invalid URL, fall through
+            }
+        }
+        // Fall back to content type
+        const mimeToExt = {
+            "image/jpeg": ".jpg",
+            "image/png": ".png",
+            "image/gif": ".gif",
+            "image/webp": ".webp",
+            "image/svg+xml": ".svg",
+            "image/bmp": ".bmp",
+            "image/tiff": ".tiff",
+        };
+        if (contentType && mimeToExt[contentType]) {
+            return mimeToExt[contentType];
+        }
+        return "";
+    }
+    buildS3Url(key) {
+        return `https://${this.awsConfig.bucket}.s3.${this.awsConfig.region}.amazonaws.com/${key}`;
+    }
+}
+exports.MediaModule = MediaModule;

package/dist/modules/media/media.types.d.ts

@@ -0,0 +1,20 @@
+export interface MediaUploadOptions {
+    /** Custom S3 key. If omitted, a UUID-based key is auto-generated. */
+    key?: string;
+    /** S3 folder prefix (e.g. "uploads"). Ignored if `key` is provided. */
+    folder?: string;
+    /** MIME content type (e.g. "image/jpeg"). Auto-detected for URL uploads. */
+    contentType?: string;
+}
+export interface MediaUploadResponse {
+    /** The S3 object key */
+    key: string;
+    /** Full S3 URL to the uploaded object */
+    url: string;
+    /** S3 bucket name */
+    bucket: string;
+    /** MIME content type of the uploaded file */
+    contentType: string;
+    /** File size in bytes */
+    size: number;
+}

package/dist/modules/media/media.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/s3-media-client.d.ts

@@ -0,0 +1,7 @@
+import { S3MediaConfig } from "./types";
+import { MediaModule } from "./modules/media";
+export declare class S3MediaClient {
+    readonly media: MediaModule;
+    private s3Client;
+    constructor(config: S3MediaConfig);
+}

package/dist/s3-media-client.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.S3MediaClient = void 0;
+const s3_client_1 = require("./lib/s3.client");
+const media_1 = require("./modules/media");
+class S3MediaClient {
+    constructor(config) {
+        this.s3Client = (0, s3_client_1.createS3Client)(config.aws);
+        this.media = new media_1.MediaModule(this.s3Client, config.aws);
+    }
+}
+exports.S3MediaClient = S3MediaClient;

package/dist/types.d.ts

@@ -0,0 +1,9 @@
+export interface AWSConfig {
+    region: string;
+    bucket: string;
+    accessKey: string;
+    secretKey: string;
+}
+export interface S3MediaConfig {
+    aws: AWSConfig;
+}

package/dist/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "cloud-service-kit",
+  "version": "1.0.0",
+  "description": "A modular cloud service toolkit for S3 media uploads, email, and more",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "cloud",
+    "s3",
+    "media",
+    "upload",
+    "aws",
+    "toolkit"
+  ],
+  "license": "UNLICENSED",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.3.0",
+    "typescript": "^5.7.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}