@haverstack/blob-adapter-s3 0.1.0

package/LICENSE

@@ -0,0 +1,7 @@
+CC0 1.0 Universal (CC0 1.0) Public Domain Dedication
+
+To the extent possible under law, the Haverstack contributors have waived all
+copyright and related or neighboring rights to Haverstack. This work is
+published from the United States.
+
+https://creativecommons.org/publicdomain/zero/1.0/

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Haverstack — S3 Blob Adapter
+ * -------------------------------------------------------
+ * Implements StackBlobAdapter over the S3 API, storing
+ * content-addressed blobs keyed by the SHA-256 hash of their
+ * bytes. Pass `endpoint` + `forcePathStyle` to target an
+ * S3-compatible store (e.g. Cloudflare R2) instead of AWS S3
+ * itself — the rest of the adapter is identical either way.
+ *
+ * Unlike blob-adapter-disk, no temp-file-plus-rename dance is
+ * needed: S3's PutObject is atomic per key, so two callers
+ * writing the same content-addressed key concurrently just
+ * write the same bytes twice — never a torn object.
+ */
+import { S3Client, type S3ClientConfig } from '@aws-sdk/client-s3';
+import type { FileId } from '@haverstack/core';
+import type { StackBlobAdapter, BlobFileInfo } from '@haverstack/core/adapter';
+export type S3BlobAdapterOptions = {
+    /** Bucket to store blobs in. */
+    bucket: string;
+    /**
+     * A pre-configured S3Client, for callers who need control over retry
+     * policy, credential providers, request middleware, etc. When omitted,
+     * a client is built from the remaining options.
+     */
+    client?: S3Client;
+    /** AWS region. Ignored when `client` is provided. */
+    region?: string;
+    /**
+     * Custom endpoint — set this together with `forcePathStyle` to target an
+     * S3-compatible store (e.g. Cloudflare R2's S3 endpoint) instead of AWS
+     * S3. Ignored when `client` is provided.
+     */
+    endpoint?: string;
+    /** Ignored when `client` is provided. */
+    forcePathStyle?: boolean;
+    /** Ignored when `client` is provided. */
+    credentials?: S3ClientConfig['credentials'];
+};
+export declare class S3BlobAdapter implements StackBlobAdapter {
+    private readonly client;
+    private readonly bucket;
+    constructor(options: S3BlobAdapterOptions);
+    private objectExists;
+    putAttachment(data: Uint8Array): Promise<FileId>;
+    getAttachment(fileId: FileId): Promise<Uint8Array>;
+    deleteAttachment(fileId: FileId): Promise<void>;
+    listFiles(): Promise<BlobFileInfo[]>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EACL,QAAQ,EAQR,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAU/E,MAAM,MAAM,oBAAoB,GAAG;IACjC,gCAAgC;IAChC,MAAM,EAAE,MAAM,CAAC;IACf;;;;OAIG;IACH,MAAM,CAAC,EAAE,QAAQ,CAAC;IAClB,qDAAqD;IACrD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,yCAAyC;IACzC,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,yCAAyC;IACzC,WAAW,CAAC,EAAE,cAAc,CAAC,aAAa,CAAC,CAAC;CAC7C,CAAC;AAEF,qBAAa,aAAc,YAAW,gBAAgB;IACpD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAW;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEpB,OAAO,EAAE,oBAAoB;YAY3B,YAAY;IAUpB,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC;IAUhD,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAelD,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAQ/C,SAAS,IAAI,OAAO,CAAC,YAAY,EAAE,CAAC;CAgB3C"}

package/dist/index.js

@@ -0,0 +1,91 @@
+/**
+ * Haverstack — S3 Blob Adapter
+ * -------------------------------------------------------
+ * Implements StackBlobAdapter over the S3 API, storing
+ * content-addressed blobs keyed by the SHA-256 hash of their
+ * bytes. Pass `endpoint` + `forcePathStyle` to target an
+ * S3-compatible store (e.g. Cloudflare R2) instead of AWS S3
+ * itself — the rest of the adapter is identical either way.
+ *
+ * Unlike blob-adapter-disk, no temp-file-plus-rename dance is
+ * needed: S3's PutObject is atomic per key, so two callers
+ * writing the same content-addressed key concurrently just
+ * write the same bytes twice — never a torn object.
+ */
+import { createHash } from 'node:crypto';
+import { S3Client, PutObjectCommand, GetObjectCommand, HeadObjectCommand, DeleteObjectCommand, ListObjectsV2Command, NoSuchKey, NotFound, } from '@aws-sdk/client-s3';
+import { StackNotFoundError, StackQueryError } from '@haverstack/core';
+const SHA256_HEX_RE = /^[0-9a-f]{64}$/;
+const assertFileId = (fileId) => {
+    if (!SHA256_HEX_RE.test(fileId)) {
+        throw new StackQueryError(`Invalid fileId: expected 64-character lowercase hex string`);
+    }
+};
+export class S3BlobAdapter {
+    client;
+    bucket;
+    constructor(options) {
+        this.bucket = options.bucket;
+        this.client =
+            options.client ??
+                new S3Client({
+                    region: options.region,
+                    endpoint: options.endpoint,
+                    forcePathStyle: options.forcePathStyle,
+                    credentials: options.credentials,
+                });
+    }
+    async objectExists(fileId) {
+        try {
+            await this.client.send(new HeadObjectCommand({ Bucket: this.bucket, Key: fileId }));
+            return true;
+        }
+        catch (err) {
+            if (err instanceof NotFound)
+                return false;
+            throw err;
+        }
+    }
+    async putAttachment(data) {
+        const fileId = createHash('sha256').update(data).digest('hex');
+        if (!(await this.objectExists(fileId))) {
+            await this.client.send(new PutObjectCommand({ Bucket: this.bucket, Key: fileId, Body: data }));
+        }
+        return fileId;
+    }
+    async getAttachment(fileId) {
+        assertFileId(fileId);
+        try {
+            const response = await this.client.send(new GetObjectCommand({ Bucket: this.bucket, Key: fileId }));
+            return await response.Body.transformToByteArray();
+        }
+        catch (err) {
+            if (err instanceof NoSuchKey) {
+                throw new StackNotFoundError(`Attachment not found: "${fileId}"`);
+            }
+            throw err;
+        }
+    }
+    async deleteAttachment(fileId) {
+        assertFileId(fileId);
+        // S3's DeleteObject is idempotent — a missing key is treated as
+        // already-deleted rather than an error, so no non-fatal catch is
+        // needed here the way blob-adapter-disk needs one for fs semantics.
+        await this.client.send(new DeleteObjectCommand({ Bucket: this.bucket, Key: fileId }));
+    }
+    async listFiles() {
+        const files = [];
+        let continuationToken;
+        do {
+            const response = await this.client.send(new ListObjectsV2Command({ Bucket: this.bucket, ContinuationToken: continuationToken }));
+            for (const obj of response.Contents ?? []) {
+                if (obj.Key && SHA256_HEX_RE.test(obj.Key) && obj.Size !== undefined && obj.LastModified) {
+                    files.push({ fileId: obj.Key, size: obj.Size, modifiedAt: obj.LastModified });
+                }
+            }
+            continuationToken = response.IsTruncated ? response.NextContinuationToken : undefined;
+        } while (continuationToken);
+        return files;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@haverstack/blob-adapter-s3",
+  "version": "0.1.0",
+  "description": "S3 (and S3-compatible) blob adapter for Haverstack",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/haverstack/core.git",
+    "directory": "packages/blob-adapter-s3"
+  },
+  "license": "CC0-1.0",
+  "keywords": [
+    "haverstack",
+    "s3",
+    "r2",
+    "blob",
+    "adapter",
+    "personal data",
+    "storage"
+  ],
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.700.0",
+    "@haverstack/core": "^0.15.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "aws-sdk-client-mock": "^4.0.0",
+    "typescript": "^5.5.0",
+    "vitest": "^2.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src tests"
+  }
+}