From cf0402cd7a485799ab5d2196ad222c6103f44913 Mon Sep 17 00:00:00 2001
From: Juergen Kunz <juergen@foss.global>
Date: Tue, 7 Apr 2026 16:28:01 +0000
Subject: [PATCH] feat(bucket): expose the underlying S3 client through
 getStorageClient()

---
 changelog.md             |  6 ++++++
 test/test.node+deno.ts   | 11 +++++++++++
 ts/00_commitinfo_data.ts |  2 +-
 ts/classes.bucket.ts     | 14 ++++++++++++++
 4 files changed, 32 insertions(+), 1 deletion(-)

diff --git a/changelog.md b/changelog.md
index 997e40b..d0244ab 100644
--- a/changelog.md
+++ b/changelog.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## 2026-04-07 - 4.6.0 - feat(bucket)
+expose the underlying S3 client through getStorageClient()
+
+- add Bucket.getStorageClient() to return the shared SmartBucket S3Client instance
+- cover the new API with a test that verifies the returned client exposes send() and matches the parent storageClient by identity
+
 ## 2026-04-07 - 4.5.2 - fix(build)
 rename npmextra config to .smartconfig and update tooling dependencies
 
diff --git a/test/test.node+deno.ts b/test/test.node+deno.ts
index e69a6b2..0944db6 100644
--- a/test/test.node+deno.ts
+++ b/test/test.node+deno.ts
@@ -24,6 +24,17 @@ tap.test('should create a valid smartbucket', async () => {
   expect(myBucket.name).toEqual(bucketName);
 });
 
+tap.test('should expose the underlying S3 client via getStorageClient()', async () => {
+  const client = myBucket.getStorageClient();
+  expect(client).toBeDefined();
+  expect(typeof (client as any).send).toEqual('function');
+  // The returned client must be the exact same instance as the parent
+  // SmartBucket's storageClient — not a copy. Use identity comparison
+  // because the S3Client contains circular references and cannot be
+  // deep-compared by tapbundle's toEqual.
+  expect(client === testSmartbucket.storageClient).toBeTrue();
+});
+
 tap.test('should clean all contents', async () => {
   await myBucket.cleanAllContents();
   expect(await myBucket.fastExists({ path: 'hithere/socool.txt' })).toBeFalse();
diff --git a/ts/00_commitinfo_data.ts b/ts/00_commitinfo_data.ts
index db4e8b5..4709ece 100644
--- a/ts/00_commitinfo_data.ts
+++ b/ts/00_commitinfo_data.ts
@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@push.rocks/smartbucket',
-  version: '4.5.2',
+  version: '4.6.0',
   description: 'A TypeScript library providing a cloud-agnostic interface for managing object storage with functionalities like bucket management, file and directory operations, and advanced features such as metadata handling and file locking.'
 }
diff --git a/ts/classes.bucket.ts b/ts/classes.bucket.ts
index f8e584f..e8ea3f2 100644
--- a/ts/classes.bucket.ts
+++ b/ts/classes.bucket.ts
@@ -49,6 +49,20 @@ export class Bucket {
     this.name = bucketName;
   }
 
+  /**
+   * Returns the underlying AWS SDK v3 S3Client for this bucket.
+   *
+   * Use this when you need to perform operations smartbucket doesn't
+   * wrap directly (e.g. lifecycle policies, bucket tagging, multipart
+   * upload control, object-lock, inventory config, etc.).
+   *
+   * The returned client is shared with the parent SmartBucket — do not
+   * call `.destroy()` on it.
+   */
+  public getStorageClient(): plugins.s3.S3Client {
+    return this.smartbucketRef.storageClient;
+  }
+
   /**
    * gets the base directory of the bucket
    */