@porulle/adapter-s3 0.1.0

package/README.md

@@ -0,0 +1,50 @@
+# @porulle/adapter-s3
+
+`StorageAdapter` for AWS S3 (or any S3-compatible bucket — DigitalOcean Spaces, MinIO, Backblaze B2 with the right `endpoint`).
+
+## Usage
+
+```ts
+import { defineConfig } from "@porulle/core";
+import { s3StorageAdapter } from "@porulle/adapter-s3";
+
+export default defineConfig({
+  storage: s3StorageAdapter({
+    bucket: "acme-media",
+    region: "us-east-1",
+    publicBaseUrl: "https://media.acme.com",     // CDN or static.acme.com
+    signedUrlExpiresIn: 3600,                     // 1 hour
+    credentials: {                                // optional — falls back to AWS credential chain
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+    },
+  }),
+  // …
+});
+```
+
+For S3-compatible providers, set `endpoint` and `forcePathStyle`:
+
+```ts
+s3StorageAdapter({
+  bucket: "acme-media",
+  region: "us-east-1",
+  endpoint: "https://nyc3.digitaloceanspaces.com",
+  forcePathStyle: true,
+  // …
+});
+```
+
+## What it implements
+
+`upload`, `getUrl` (returns `publicBaseUrl/<key>`), `getSignedUrl` (presigned GET via `@aws-sdk/s3-request-presigner`), `delete`, `list` (paginated via `ListObjectsV2`).
+
+## Notes
+
+- Bring your own AWS SDK config — the adapter doesn't override credential resolution; it uses `@aws-sdk/client-s3` defaults if you omit `credentials`.
+- The `client` and `signUrl` options exist for unit tests; production code should leave them unset.
+
+## See also
+
+- `@porulle/adapter-r2` — Cloudflare R2 (no AWS SDK, lighter)
+- [`SECURITY.md`](../../../SECURITY.md) — media-upload MIME validation is enforced in `@porulle/core`

package/dist/src/index.d.ts

@@ -0,0 +1,21 @@
+import { type S3ClientConfig } from "@aws-sdk/client-s3";
+import { type StorageAdapter } from "@porulle/core";
+interface S3ClientLike {
+    send(command: unknown): Promise<any>;
+}
+export interface S3StorageAdapterOptions {
+    bucket: string;
+    region: string;
+    endpoint?: string;
+    forcePathStyle?: boolean;
+    publicBaseUrl?: string;
+    signedUrlExpiresIn?: number;
+    credentials?: S3ClientConfig["credentials"];
+    client?: S3ClientLike;
+    signUrl?: (client: S3ClientLike, command: unknown, options: {
+        expiresIn: number;
+    }) => Promise<string>;
+}
+export declare function s3StorageAdapter(options: S3StorageAdapterOptions): StorageAdapter;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAML,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,eAAe,CAAC;AAE1E,UAAU,YAAY;IACpB,IAAI,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;CACtC;AAED,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,WAAW,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;IAC5C,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvG;AAuBD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,cAAc,CA6GjF"}

package/dist/src/index.js

@@ -0,0 +1,112 @@
+import { DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command, PutObjectCommand, S3Client, } from "@aws-sdk/client-s3";
+import { getSignedUrl } from "@aws-sdk/s3-request-presigner";
+import { Err, Ok } from "@porulle/core";
+async function toArrayBuffer(data) {
+    if (data instanceof ArrayBuffer)
+        return data;
+    return new Response(data).arrayBuffer();
+}
+function objectUrl(options, key) {
+    if (options.publicBaseUrl) {
+        return `${options.publicBaseUrl.replace(/\/$/, "")}/${key}`;
+    }
+    if (options.endpoint) {
+        const endpoint = options.endpoint.replace(/\/$/, "");
+        if (options.forcePathStyle) {
+            return `${endpoint}/${options.bucket}/${key}`;
+        }
+        return `${endpoint}/${key}`;
+    }
+    return `https://${options.bucket}.s3.${options.region}.amazonaws.com/${key}`;
+}
+export function s3StorageAdapter(options) {
+    const client = options.client ??
+        new S3Client({
+            region: options.region,
+            ...(options.endpoint ? { endpoint: options.endpoint } : {}),
+            ...(options.forcePathStyle !== undefined ? { forcePathStyle: options.forcePathStyle } : {}),
+            ...(options.credentials ? { credentials: options.credentials } : {}),
+        });
+    const signUrl = options.signUrl ?? (async (currentClient, command, config) => getSignedUrl(currentClient, command, config));
+    return {
+        providerId: "s3",
+        async upload(key, data, contentType) {
+            try {
+                const body = await toArrayBuffer(data);
+                await client.send(new PutObjectCommand({
+                    Bucket: options.bucket,
+                    Key: key,
+                    Body: new Uint8Array(body),
+                    ContentType: contentType,
+                }));
+                return Ok({
+                    key,
+                    url: objectUrl(options, key),
+                    contentType,
+                    size: body.byteLength,
+                });
+            }
+            catch (error) {
+                return Err({
+                    code: "S3_UPLOAD_FAILED",
+                    message: error instanceof Error ? error.message : "Failed to upload to S3.",
+                });
+            }
+        },
+        async getUrl(key) {
+            return Ok(objectUrl(options, key));
+        },
+        async getSignedUrl(key, expiresIn) {
+            try {
+                const ttl = expiresIn > 0 ? expiresIn : options.signedUrlExpiresIn ?? 900;
+                const url = await signUrl(client, new GetObjectCommand({
+                    Bucket: options.bucket,
+                    Key: key,
+                }), { expiresIn: ttl });
+                return Ok(url);
+            }
+            catch (error) {
+                return Err({
+                    code: "S3_SIGNED_URL_FAILED",
+                    message: error instanceof Error ? error.message : "Failed to generate signed URL.",
+                });
+            }
+        },
+        async delete(key) {
+            try {
+                await client.send(new DeleteObjectCommand({
+                    Bucket: options.bucket,
+                    Key: key,
+                }));
+                return Ok(undefined);
+            }
+            catch (error) {
+                return Err({
+                    code: "S3_DELETE_FAILED",
+                    message: error instanceof Error ? error.message : "Failed to delete object from S3.",
+                });
+            }
+        },
+        async list(prefix) {
+            try {
+                const listed = await client.send(new ListObjectsV2Command({
+                    Bucket: options.bucket,
+                    Prefix: prefix,
+                }));
+                const items = (listed.Contents ?? []).map((item) => ({
+                    key: String(item.Key ?? ""),
+                    url: objectUrl(options, String(item.Key ?? "")),
+                    contentType: "application/octet-stream",
+                    size: typeof item.Size === "number" ? item.Size : undefined,
+                }));
+                return Ok(items.filter((item) => item.key.length > 0));
+            }
+            catch (error) {
+                return Err({
+                    code: "S3_LIST_FAILED",
+                    message: error instanceof Error ? error.message : "Failed to list S3 objects.",
+                });
+            }
+        },
+    };
+}