@cat-factory/provider-s3 0.2.5 → 0.2.7

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 Igor Savin
-
-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.
+MIT License
+
+Copyright (c) 2026 Igor Savin
+
+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/dist/index.d.ts

@@ -0,0 +1,43 @@
+import type { BinaryBlobBackend } from '@cat-factory/kernel';
+export interface S3BinaryBlobBackendConfig {
+    region: string;
+    bucket: string;
+    /** Optional key prefix, e.g. `artifacts/`. Joined to the artifact's storage key. */
+    prefix?: string;
+    /** Optional custom endpoint (S3-compatible stores: MinIO, etc.). */
+    endpoint?: string;
+    /** Force path-style addressing (needed by most S3-compatible stores). */
+    forcePathStyle?: boolean;
+    /** Explicit credentials; omit to use the default AWS credential chain. */
+    credentials?: {
+        accessKeyId: string;
+        secretAccessKey: string;
+        sessionToken?: string;
+    };
+}
+/**
+ * AWS S3 (or S3-compatible) blob backend for binary artifacts. Implements the kernel
+ * {@link BinaryBlobBackend} port; the metadata still lives in the runtime's DB. Opt-in:
+ * a deployment selects it via `BINARY_STORAGE_BACKEND=s3`.
+ *
+ * The (heavy) `@aws-sdk/client-s3` is imported LAZILY on first use, not at module load:
+ * a facade statically imports this class to wire its container, but a deployment that
+ * runs the `db` (or no) blob backend then never pays the SDK's load cost — the SDK is
+ * only pulled in when an S3 operation actually executes.
+ */
+export declare class S3BinaryBlobBackend implements BinaryBlobBackend {
+    private readonly config;
+    readonly kind: 's3';
+    private readonly bucket;
+    private readonly prefix;
+    /** Cached, lazily-built `{ sdk, client }` so the AWS SDK loads at most once on first I/O. */
+    private clientPromise;
+    constructor(config: S3BinaryBlobBackendConfig);
+    /** Dynamically import the AWS SDK and build the client (memoised). */
+    private resolveClient;
+    private fullKey;
+    put(key: string, bytes: Uint8Array, contentType: string): Promise<void>;
+    get(key: string): Promise<Uint8Array | null>;
+    delete(key: string): Promise<void>;
+}
+//# 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":"AAOA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAA;AAE5D,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,oFAAoF;IACpF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,oEAAoE;IACpE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,yEAAyE;IACzE,cAAc,CAAC,EAAE,OAAO,CAAA;IACxB,0EAA0E;IAC1E,WAAW,CAAC,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAC;QAAC,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAA;CACtF;AAUD;;;;;;;;;GASG;AACH,qBAAa,mBAAoB,YAAW,iBAAiB;IAO/C,OAAO,CAAC,QAAQ,CAAC,MAAM;IANnC,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,6FAA6F;IAC7F,OAAO,CAAC,aAAa,CAAuD;IAE5E,YAA6B,MAAM,EAAE,yBAAyB,EAG7D;IAED,sEAAsE;YACxD,aAAa;IAc3B,OAAO,CAAC,OAAO;IAIT,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAU5E;IAEK,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CAYjD;IAEK,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAGvC;CACF"}

package/dist/index.js

@@ -0,0 +1,71 @@
+/**
+ * AWS S3 (or S3-compatible) blob backend for binary artifacts. Implements the kernel
+ * {@link BinaryBlobBackend} port; the metadata still lives in the runtime's DB. Opt-in:
+ * a deployment selects it via `BINARY_STORAGE_BACKEND=s3`.
+ *
+ * The (heavy) `@aws-sdk/client-s3` is imported LAZILY on first use, not at module load:
+ * a facade statically imports this class to wire its container, but a deployment that
+ * runs the `db` (or no) blob backend then never pays the SDK's load cost — the SDK is
+ * only pulled in when an S3 operation actually executes.
+ */
+export class S3BinaryBlobBackend {
+    config;
+    kind = 's3';
+    bucket;
+    prefix;
+    /** Cached, lazily-built `{ sdk, client }` so the AWS SDK loads at most once on first I/O. */
+    clientPromise;
+    constructor(config) {
+        this.config = config;
+        this.bucket = config.bucket;
+        this.prefix = config.prefix ? config.prefix.replace(/\/+$/, '') + '/' : '';
+    }
+    /** Dynamically import the AWS SDK and build the client (memoised). */
+    async resolveClient() {
+        if (!this.clientPromise) {
+            this.clientPromise = (async () => {
+                const sdk = (await import('@aws-sdk/client-s3'));
+                const clientConfig = { region: this.config.region };
+                if (this.config.endpoint)
+                    clientConfig.endpoint = this.config.endpoint;
+                if (this.config.forcePathStyle)
+                    clientConfig.forcePathStyle = this.config.forcePathStyle;
+                if (this.config.credentials)
+                    clientConfig.credentials = this.config.credentials;
+                return { sdk, client: new sdk.S3Client(clientConfig) };
+            })();
+        }
+        return this.clientPromise;
+    }
+    fullKey(key) {
+        return `${this.prefix}${key}`;
+    }
+    async put(key, bytes, contentType) {
+        const { sdk, client } = await this.resolveClient();
+        await client.send(new sdk.PutObjectCommand({
+            Bucket: this.bucket,
+            Key: this.fullKey(key),
+            Body: bytes,
+            ContentType: contentType,
+        }));
+    }
+    async get(key) {
+        const { sdk, client } = await this.resolveClient();
+        try {
+            const out = await client.send(new sdk.GetObjectCommand({ Bucket: this.bucket, Key: this.fullKey(key) }));
+            if (!out.Body)
+                return null;
+            return new Uint8Array(await out.Body.transformToByteArray());
+        }
+        catch (error) {
+            if (error.name === 'NoSuchKey')
+                return null;
+            throw error;
+        }
+    }
+    async delete(key) {
+        const { sdk, client } = await this.resolveClient();
+        await client.send(new sdk.DeleteObjectCommand({ Bucket: this.bucket, Key: this.fullKey(key) }));
+    }
+}
+//# 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

@@ -1,6 +1,6 @@
 {
   "name": "@cat-factory/provider-s3",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Opt-in AWS S3 blob backend for the Agent Architecture Board's binary-artifact storage abstraction. Implements the kernel BinaryBlobBackend port over an S3 bucket.",
   "repository": {
     "type": "git",
@@ -25,7 +25,7 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.700.0",
-    "@cat-factory/kernel": "0.45.0"
+    "@cat-factory/kernel": "0.45.2"
   },
   "devDependencies": {
     "typescript": "7.0.1-rc"