feat(bucket): expose the underlying S3 client through getStorageClient()

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
 

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();

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.'
 }

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
    */