@venizia/ignis-docs 0.0.7-2 → 0.0.8-0

package/wiki/{references → extensions}/helpers/queue/index.md

@@ -1,13 +1,17 @@
 # Queue
 
-Message queuing and asynchronous task management with BullMQ, MQTT, and in-memory solutions.
+Message queuing and asynchronous task management with BullMQ, Kafka, MQTT, and in-memory solutions.
 
 ## Quick Reference
 
 | Class | Extends | Peer Dependency | Use Case |
 |-------|---------|-----------------|----------|
-| **BullMQHelper** | `BaseHelper` | `bullmq` (^5.63.1) | Redis-backed job queue -- background processing, task scheduling |
-| **MQTTClientHelper** | `BaseHelper` | `mqtt` (^5.14.1) | MQTT broker messaging -- real-time events, IoT |
+| **BullMQHelper** | `BaseHelper` | `bullmq` (^5.70.0) | Redis-backed job queue -- background processing, task scheduling |
+| **KafkaProducerHelper** | `BaseKafkaHelper` | `@platformatic/kafka` (^1.30.0) | Kafka message producer with transaction support |
+| **KafkaConsumerHelper** | `BaseKafkaHelper` | `@platformatic/kafka` (^1.30.0) | Kafka message consumer with lag monitoring |
+| **KafkaAdminHelper** | `BaseKafkaHelper` | `@platformatic/kafka` (^1.30.0) | Kafka admin operations (topic management) |
+| **KafkaSchemaRegistryHelper** | `BaseHelper` | `@platformatic/kafka` (^1.30.0) | Confluent Schema Registry integration |
+| **MQTTClientHelper** | `BaseHelper` | `mqtt` (^5.15.0) | MQTT broker messaging -- real-time events, IoT |
 | **QueueHelper** | `BaseHelper` | None | In-memory generator queue -- sequential tasks, single process |
 
 #### Common Operations
@@ -15,6 +19,7 @@ Message queuing and asynchronous task management with BullMQ, MQTT, and in-memor
 | Helper | Subscribe / Consume | Publish / Produce |
 |--------|---------------------|-------------------|
 | **BullMQ** | Create with `role: 'worker'` | `queue.add(name, data)` via the exposed BullMQ `Queue` instance |
+| **Kafka** | `consumer.start({ topics })` | `producer.getProducer().send({ messages })` |
 | **MQTT** | `subscribe({ topics })` | `publish({ topic, message })` |
 | **In-Memory** | `new QueueHelper({ onMessage })` | `enqueue(payload)` |
 
@@ -29,6 +34,33 @@ import type { TQueueStatus, TQueueElement } from '@venizia/ignis-helpers';
 import { BullMQHelper } from '@venizia/ignis-helpers/bullmq';
 import type { TBullQueueRole } from '@venizia/ignis-helpers/bullmq';
 
+// Kafka (separate export path)
+import {
+  KafkaProducerHelper,
+  KafkaConsumerHelper,
+  KafkaAdminHelper,
+  KafkaSchemaRegistryHelper,
+  BaseKafkaHelper,
+} from '@venizia/ignis-helpers/kafka';
+import type {
+  IKafkaProducerOptions,
+  IKafkaConsumerOptions,
+  IKafkaAdminOptions,
+  IKafkaSchemaRegistryOptions,
+  IKafkaConsumeStartOptions,
+  IKafkaTransactionContext,
+  TKafkaBrokerEventCallback,
+  TKafkaMessageCallback,
+  TKafkaMessageDoneCallback,
+  TKafkaMessageErrorCallback,
+  TKafkaGroupJoinCallback,
+  TKafkaGroupLeaveCallback,
+  TKafkaGroupRebalanceCallback,
+  TKafkaHeartbeatErrorCallback,
+  TKafkaLagCallback,
+  TKafkaLagErrorCallback,
+} from '@venizia/ignis-helpers/kafka';
+
 // MQTT (separate export path)
 import { MQTTClientHelper } from '@venizia/ignis-helpers/mqtt';
 import type { IMQTTClientOptions } from '@venizia/ignis-helpers/mqtt';
@@ -36,7 +68,7 @@ import type { IMQTTClientOptions } from '@venizia/ignis-helpers/mqtt';
 
 ## Creating an Instance
 
-All three queue helpers extend `BaseHelper`, providing scoped logging via `this.logger`.
+All queue helpers extend `BaseHelper` (Kafka helpers via `BaseKafkaHelper`), providing scoped logging via `this.logger`.
 
 ### BullMQHelper
 
@@ -176,6 +208,178 @@ Each element in the queue is wrapped in a `TQueueElement`:
 type TQueueElement<T> = { isLocked: boolean; payload: T };
 ```
 
+### Kafka Producer
+
+The `KafkaProducerHelper` wraps `@platformatic/kafka` Producer with lifecycle management, health tracking, and transaction support.
+
+```typescript
+import { KafkaProducerHelper } from '@venizia/ignis-helpers/kafka';
+
+const producer = KafkaProducerHelper.newInstance({
+  bootstrapBrokers: ['127.0.0.1:29092'],
+  clientId: 'my-producer',
+  acks: -1,
+  idempotent: true,
+  onBrokerConnect: ({ broker }) => {
+    console.log(`Connected to ${broker.host}:${broker.port}`);
+  },
+  onBrokerDisconnect: ({ broker }) => {
+    console.log(`Disconnected from ${broker.host}:${broker.port}`);
+  },
+});
+```
+
+#### IKafkaProducerOptions
+
+`IKafkaProducerOptions<KeyType, ValueType, HeaderKeyType, HeaderValueType>` extends `IKafkaConnectionOptions`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `bootstrapBrokers` | `string[]` | -- | Kafka broker addresses. |
+| `clientId` | `string` | -- | Client identifier. |
+| `identifier` | `string` | `'kafka-producer'` | Scoped logging identifier. |
+| `acks` | `0 \| 1 \| -1` | -- | Acknowledgment mode. `0` = none, `1` = leader, `-1` = all ISR. |
+| `idempotent` | `boolean` | -- | Enable idempotent producer. |
+| `transactionalId` | `string` | -- | Transactional ID (required for transactions with `idempotent: true`). |
+| `compression` | `CompressionAlgorithmValue` | -- | Message compression algorithm. |
+| `strict` | `boolean` | `true` | Strict mode for topic validation. |
+| `autocreateTopics` | `boolean` | `false` | Auto-create topics on send. |
+| `retries` | `number` | `3` | Number of retries on failure. |
+| `retryDelay` | `number` | `1000` | Delay between retries in milliseconds. |
+| `shutdownTimeout` | `number` | `30000` | Graceful shutdown timeout in milliseconds. |
+| `serializers` | `Partial<Serializers<...>>` | -- | Custom key/value/header serializers. |
+| `registry` | `SchemaRegistry<...>` | -- | Schema registry for serialization. |
+| `sasl` | `SASLOptions` | -- | SASL authentication options. |
+| `tls` | `TLSOptions` | -- | TLS connection options. |
+| `ssl` | `SSLOptions` | -- | SSL connection options. |
+| `connectTimeout` | `number` | -- | Connection timeout in milliseconds. |
+| `requestTimeout` | `number` | -- | Request timeout in milliseconds. |
+| `onBrokerConnect` | `TKafkaBrokerEventCallback` | -- | Callback when a broker connects. |
+| `onBrokerDisconnect` | `TKafkaBrokerEventCallback` | -- | Callback when a broker disconnects. |
+
+### Kafka Consumer
+
+The `KafkaConsumerHelper` wraps `@platformatic/kafka` Consumer with message processing callbacks, consumer group lifecycle events, and lag monitoring.
+
+```typescript
+import { KafkaConsumerHelper } from '@venizia/ignis-helpers/kafka';
+
+const consumer = KafkaConsumerHelper.newInstance({
+  bootstrapBrokers: ['127.0.0.1:29092'],
+  clientId: 'my-consumer',
+  groupId: 'my-consumer-group',
+  onMessage: async ({ message }) => {
+    console.log('Received:', message.value);
+    await message.commit();
+  },
+  onMessageError: ({ error }) => {
+    console.error('Error:', error);
+  },
+  onGroupJoin: ({ groupId, memberId }) => {
+    console.log(`Joined ${groupId} as ${memberId}`);
+  },
+});
+```
+
+#### IKafkaConsumerOptions
+
+`IKafkaConsumerOptions<KeyType, ValueType, HeaderKeyType, HeaderValueType>` extends `IKafkaConnectionOptions`.
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `bootstrapBrokers` | `string[]` | -- | Kafka broker addresses. |
+| `clientId` | `string` | -- | Client identifier. |
+| `groupId` | `string` | -- | Consumer group ID. Required. |
+| `identifier` | `string` | `'kafka-consumer'` | Scoped logging identifier. |
+| `groupProtocol` | `'classic' \| 'consumer'` | `'classic'` | Consumer group protocol. |
+| `groupInstanceId` | `string` | -- | Static group membership instance ID. |
+| `autocommit` | `boolean \| number` | `false` | Auto-commit offsets. `false` = manual, `true` or number = interval. |
+| `sessionTimeout` | `number` | `30000` | Session timeout in milliseconds. |
+| `heartbeatInterval` | `number` | `3000` | Heartbeat interval in milliseconds. |
+| `rebalanceTimeout` | `number` | `sessionTimeout` | Rebalance timeout in milliseconds. |
+| `highWaterMark` | `number` | `1024` | Stream high water mark. |
+| `minBytes` | `number` | `1` | Minimum bytes to fetch per request. |
+| `maxBytes` | `number` | -- | Maximum bytes to fetch per request. |
+| `maxWaitTime` | `number` | -- | Maximum wait time for fetch in milliseconds. |
+| `metadataMaxAge` | `number` | `300000` | Metadata cache max age in milliseconds. |
+| `retries` | `number` | `3` | Number of retries on failure. |
+| `retryDelay` | `number` | `1000` | Delay between retries in milliseconds. |
+| `shutdownTimeout` | `number` | `30000` | Graceful shutdown timeout in milliseconds. |
+| `deserializers` | `Partial<Deserializers<...>>` | -- | Custom key/value/header deserializers. |
+| `registry` | `SchemaRegistry<...>` | -- | Schema registry for deserialization. |
+| `onBrokerConnect` | `TKafkaBrokerEventCallback` | -- | Callback when a broker connects. |
+| `onBrokerDisconnect` | `TKafkaBrokerEventCallback` | -- | Callback when a broker disconnects. |
+| `onMessage` | `TKafkaMessageCallback` | -- | Message processing callback. |
+| `onMessageDone` | `TKafkaMessageDoneCallback` | -- | Callback after message processing completes. |
+| `onMessageError` | `TKafkaMessageErrorCallback` | -- | Callback on message processing error. |
+| `onGroupJoin` | `TKafkaGroupJoinCallback` | -- | Callback when consumer joins the group. |
+| `onGroupLeave` | `TKafkaGroupLeaveCallback` | -- | Callback when consumer leaves the group. |
+| `onGroupRebalance` | `TKafkaGroupRebalanceCallback` | -- | Callback on group rebalance. |
+| `onHeartbeatError` | `TKafkaHeartbeatErrorCallback` | -- | Callback on heartbeat error. |
+| `onLag` | `TKafkaLagCallback` | -- | Callback with lag offset data. |
+| `onLagError` | `TKafkaLagErrorCallback` | -- | Callback on lag monitoring error. |
+
+### Kafka Admin
+
+The `KafkaAdminHelper` wraps `@platformatic/kafka` Admin for topic and cluster management.
+
+```typescript
+import { KafkaAdminHelper } from '@venizia/ignis-helpers/kafka';
+
+const admin = KafkaAdminHelper.newInstance({
+  bootstrapBrokers: ['127.0.0.1:29092'],
+  clientId: 'my-admin',
+  onBrokerConnect: ({ broker }) => {
+    console.log(`Connected to ${broker.host}:${broker.port}`);
+  },
+});
+
+// Access the full Admin API directly
+const adminClient = admin.getAdmin();
+await adminClient.createTopics({ topics: ['my-topic'], partitions: 3, replicas: 1 });
+```
+
+#### IKafkaAdminOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `bootstrapBrokers` | `string[]` | -- | Kafka broker addresses. |
+| `clientId` | `string` | -- | Client identifier. |
+| `identifier` | `string` | `'kafka-admin'` | Scoped logging identifier. |
+| `retries` | `number` | `3` | Number of retries on failure. |
+| `retryDelay` | `number` | `1000` | Delay between retries in milliseconds. |
+| `shutdownTimeout` | `number` | `30000` | Graceful shutdown timeout in milliseconds. |
+| `onBrokerConnect` | `TKafkaBrokerEventCallback` | -- | Callback when a broker connects. |
+| `onBrokerDisconnect` | `TKafkaBrokerEventCallback` | -- | Callback when a broker disconnects. |
+
+### Kafka Schema Registry
+
+The `KafkaSchemaRegistryHelper` wraps `@platformatic/kafka` ConfluentSchemaRegistry for Avro/Protobuf/JSON schema integration with producer and consumer helpers.
+
+```typescript
+import { KafkaSchemaRegistryHelper, KafkaProducerHelper } from '@venizia/ignis-helpers/kafka';
+
+const schemaRegistry = KafkaSchemaRegistryHelper.newInstance({
+  url: 'http://localhost:8081',
+});
+
+const producer = KafkaProducerHelper.newInstance({
+  bootstrapBrokers: ['127.0.0.1:29092'],
+  clientId: 'my-producer',
+  registry: schemaRegistry.getRegistry(),
+});
+```
+
+#### IKafkaSchemaRegistryOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `url` | `string` | -- | Schema Registry URL. |
+| `identifier` | `string` | `'kafka-schema-registry'` | Scoped logging identifier. |
+| `auth` | `object` | -- | Authentication credentials. |
+| `protobufTypeMapper` | `function` | -- | Protobuf type mapping function. |
+| `jsonValidateSend` | `boolean` | -- | Validate JSON schemas on send. |
+
 ## Usage
 
 ### BullMQ -- Adding Jobs
@@ -334,6 +538,152 @@ const client = new MQTTClientHelper({
 });
 ```
 
+### Kafka -- Producing Messages
+
+Use `getProducer()` to access the underlying `@platformatic/kafka` Producer and send messages.
+
+```typescript
+const producer = KafkaProducerHelper.newInstance({
+  bootstrapBrokers: ['127.0.0.1:29092'],
+  clientId: 'my-producer',
+  acks: -1,
+});
+
+// Send messages via the underlying producer
+await producer.getProducer().send({
+  messages: [
+    { topic: 'orders', key: 'order-1', value: JSON.stringify({ item: 'widget' }) },
+  ],
+});
+
+// Health check
+producer.isHealthy(); // true when connected to a broker
+```
+
+### Kafka -- Consuming Messages
+
+Call `start()` to begin consuming from topics. Messages are delivered via the `onMessage` callback.
+
+```typescript
+const consumer = KafkaConsumerHelper.newInstance({
+  bootstrapBrokers: ['127.0.0.1:29092'],
+  clientId: 'my-consumer',
+  groupId: 'my-group',
+  onMessage: async ({ message }) => {
+    console.log('Key:', message.key, 'Value:', message.value);
+    await message.commit();
+  },
+  onMessageDone: async ({ message }) => {
+    console.log('Processing complete for offset:', message.offset);
+  },
+  onMessageError: ({ error, message }) => {
+    console.error('Processing failed:', error.message);
+  },
+});
+
+await consumer.start({
+  topics: ['orders'],
+  mode: 'committed',          // Default: 'committed'
+  fallbackMode: 'latest',     // Default: 'latest'
+});
+```
+
+#### IKafkaConsumeStartOptions
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `topics` | `string[]` | -- | Topics to consume from. |
+| `mode` | `MessagesStreamModeValue` | `'committed'` | Consume mode. |
+| `fallbackMode` | `MessagesStreamFallbackModeValue` | `'latest'` | Fallback mode when no committed offset exists. |
+
+### Kafka -- Lag Monitoring
+
+Monitor consumer lag to detect processing delays.
+
+```typescript
+consumer.startLagMonitoring({
+  topics: ['orders'],
+  interval: 30_000, // Default: 30 seconds
+});
+
+// Stop monitoring
+consumer.stopLagMonitoring();
+```
+
+Use the `onLag` and `onLagError` callbacks to react to lag data:
+
+```typescript
+const consumer = KafkaConsumerHelper.newInstance({
+  // ...
+  onLag: ({ lag }) => {
+    console.log('Current lag offsets:', lag);
+  },
+  onLagError: ({ error }) => {
+    console.error('Lag monitoring error:', error);
+  },
+});
+```
+
+### Kafka -- Transactions
+
+The `KafkaProducerHelper` supports exactly-once semantics via transactions. Requires `transactionalId` and `idempotent: true`.
+
+```typescript
+const producer = KafkaProducerHelper.newInstance({
+  bootstrapBrokers: ['127.0.0.1:29092'],
+  clientId: 'transactional-producer',
+  transactionalId: 'my-tx-id',
+  idempotent: true,
+  acks: -1,
+});
+
+const result = await producer.runInTransaction(async ({ send, addConsumer, addOffset }) => {
+  return send({
+    messages: [
+      { topic: 'orders', key: 'o1', value: JSON.stringify({ status: 'created' }) },
+    ],
+  });
+});
+```
+
+The transaction context provides:
+
+| Method | Description |
+|--------|-------------|
+| `send(opts)` | Send messages within the transaction. Returns `ProduceResult`. |
+| `addConsumer(consumer)` | Add a consumer to the transaction for read-process-write patterns. |
+| `addOffset(message)` | Commit consumer offsets as part of the transaction. |
+| `transaction` | The underlying transaction object for advanced operations. |
+
+If the callback throws, the transaction is automatically aborted.
+
+### Kafka -- Health Checks
+
+All Kafka helpers provide health checking via `BaseKafkaHelper`:
+
+```typescript
+producer.isHealthy();      // true when connected
+consumer.isReady();        // true when connected AND active (consuming)
+admin.getHealthStatus();   // 'connected' | 'disconnected' | 'unknown'
+```
+
+### Kafka -- Graceful Shutdown
+
+All Kafka helpers support graceful shutdown with an optional force flag and configurable timeout (default: 30 seconds).
+
+```typescript
+// Graceful shutdown (waits up to shutdownTimeout, then forces)
+await producer.close();
+await consumer.close();
+await admin.close();
+
+// Force immediate shutdown
+await producer.close({ isForce: true });
+await consumer.close({ isForce: true });
+```
+
+For consumers, `close()` also stops lag monitoring and closes the message stream before closing the client.
+
 ### In-Memory Queue -- Enqueueing and Processing
 
 With `autoDispatch: true` (default), elements are processed automatically as they are enqueued.
@@ -463,6 +813,51 @@ queue.close();
 | `queue` | `Queue<TQueueElement, TQueueResult>` | BullMQ `Queue` instance (available when `role: 'queue'`). |
 | `worker` | `Worker<TQueueElement, TQueueResult>` | BullMQ `Worker` instance (available when `role: 'worker'`). |
 
+### KafkaProducerHelper
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `static newInstance(opts)` | `KafkaProducerHelper` | Factory method. |
+| `getProducer()` | `Producer` | Access the underlying `@platformatic/kafka` Producer. |
+| `runInTransaction(callback)` | `Promise<ResultType>` | Execute a callback within a Kafka transaction. Auto-commits or aborts. |
+| `isHealthy()` | `boolean` | Returns `true` when connected to a broker. |
+| `getHealthStatus()` | `TKafkaHealthStatus` | Returns `'connected'`, `'disconnected'`, or `'unknown'`. |
+| `close(opts?)` | `Promise<void>` | Graceful shutdown. `opts: { isForce?: boolean }` |
+
+### KafkaConsumerHelper
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `static newInstance(opts)` | `KafkaConsumerHelper` | Factory method. |
+| `getConsumer()` | `Consumer` | Access the underlying `@platformatic/kafka` Consumer. |
+| `getStream()` | `MessagesStream \| null` | Access the current message stream (null if not started). |
+| `start(opts)` | `Promise<void>` | Start consuming. `opts: { topics, mode?, fallbackMode? }` |
+| `isReady()` | `boolean` | Returns `true` when connected AND actively consuming. |
+| `isHealthy()` | `boolean` | Returns `true` when connected to a broker. |
+| `getHealthStatus()` | `TKafkaHealthStatus` | Returns `'connected'`, `'disconnected'`, or `'unknown'`. |
+| `startLagMonitoring(opts)` | `void` | Start lag monitoring. `opts: { topics, interval? }` |
+| `stopLagMonitoring()` | `void` | Stop lag monitoring. |
+| `close(opts?)` | `Promise<void>` | Graceful shutdown. Stops monitoring, closes stream, then client. |
+
+### KafkaAdminHelper
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `static newInstance(opts)` | `KafkaAdminHelper` | Factory method. |
+| `getAdmin()` | `Admin` | Access the underlying `@platformatic/kafka` Admin. |
+| `isHealthy()` | `boolean` | Returns `true` when connected to a broker. |
+| `getHealthStatus()` | `TKafkaHealthStatus` | Returns `'connected'`, `'disconnected'`, or `'unknown'`. |
+| `close(opts?)` | `Promise<void>` | Graceful shutdown. `opts: { isForce?: boolean }` |
+
+### KafkaSchemaRegistryHelper
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `static newInstance(opts)` | `KafkaSchemaRegistryHelper` | Factory method. |
+| `getRegistry()` | `ConfluentSchemaRegistry` | Access the underlying schema registry. |
+| `getSerializers()` | `Serializers` | Get serializers for use with a producer. |
+| `getDeserializers()` | `Deserializers` | Get deserializers for use with a consumer. |
+
 ### MQTTClientHelper
 
 | Method | Returns | Description |
@@ -587,3 +982,4 @@ const newQueue = new QueueHelper<string>({
 - **External Resources:**
   - [BullMQ Documentation](https://docs.bullmq.io/) -- BullMQ queue library
   - [MQTT.js](https://github.com/mqttjs/MQTT.js) -- MQTT client library
+  - [@platformatic/kafka](https://github.com/platformatic/kafka) -- Kafka client library

package/wiki/{references → extensions}/helpers/storage/api.md

@@ -7,7 +7,8 @@ The storage system uses a class hierarchy with an abstract base class providing
 ```
 BaseHelper
 ├── BaseStorageHelper (abstract, implements IStorageHelper)
-│   ├── MinioHelper       -- S3-compatible object storage
+│   ├── MinioHelper       -- S3-compatible object storage (minio SDK)
+│   ├── BunS3Helper       -- S3-compatible object storage (Bun-native S3Client)
 │   └── DiskHelper        -- Local filesystem storage
 └── MemoryStorageHelper   -- In-memory key-value store
 ```
@@ -117,7 +118,7 @@ Categorizes a MIME type into a broad file type group using the `MimeTypes` const
 
 ### Abstract Methods
 
-The following methods are declared abstract in `BaseStorageHelper` and implemented by `MinioHelper` and `DiskHelper`:
+The following methods are declared abstract in `BaseStorageHelper` and implemented by `MinioHelper`, `BunS3Helper`, and `DiskHelper`:
 
 ```typescript
 abstract isBucketExists(opts: { name: string }): Promise<boolean>;
@@ -173,12 +174,6 @@ interface IMinioHelperOptions extends IStorageHelperOptions, ClientOptions {}
 
 All additional `minio.ClientOptions` properties are also accepted and passed to the underlying client.
 
-### Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `client` | `minio.Client` | The underlying MinIO client instance. Accessible for direct SDK operations. |
-
 ### Methods
 
 #### isBucketExists
@@ -322,6 +317,159 @@ Lists objects in a bucket using a streaming approach via `client.listObjects()`.
 | `opts.useRecursive` | `boolean` | `false` | List recursively through subdirectories. |
 | `opts.maxKeys` | `number` | `undefined` | Maximum number of objects to return. |
 
+## BunS3Helper
+
+S3-compatible object storage using Bun's native `S3Client`. Extends `BaseStorageHelper`. Requires the Bun runtime.
+
+Bucket management operations (list, create, delete) use AWS Signature V4 signed requests built from scratch via the `buildSignedRequest` utility. Object operations (upload, get, stat, delete, list) use Bun's native S3 API.
+
+### Constructor
+
+```typescript
+constructor(options: IBunS3HelperOptions)
+```
+
+Creates a Bun `S3Client` internally and stores credentials for bucket management requests.
+
+```typescript
+interface IBunS3HelperOptions extends IStorageHelperOptions {
+  accessKey: string;
+  secretKey: string;
+  endpoint: string;
+  region?: string;
+  sessionToken?: string;
+}
+```
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `options.accessKey` | `string` | -- | S3 access key credential. |
+| `options.secretKey` | `string` | -- | S3 secret key credential. |
+| `options.endpoint` | `string` | -- | S3-compatible endpoint URL. |
+| `options.region` | `string` | `'us-east-1'` | AWS region for signing. |
+| `options.sessionToken` | `string` | -- | Optional session token for temporary credentials. |
+| `options.scope` | `string` | `'BunS3Helper'` | Logger scope name. |
+| `options.identifier` | `string` | `'BunS3Helper'` | Helper identifier. |
+
+### Methods
+
+#### isBucketExists
+
+```typescript
+async isBucketExists(opts: { name: string }): Promise<boolean>
+```
+
+Returns `false` if the name fails `isValidName()`. Otherwise attempts a `list({ maxKeys: 1 })` against the bucket. Returns `false` on any error.
+
+#### getBuckets
+
+```typescript
+async getBuckets(): Promise<IBucketInfo[]>
+```
+
+Lists all buckets via a signed `GET /` request. Parses the XML response to extract bucket names and creation dates.
+
+#### getBucket
+
+```typescript
+async getBucket(opts: { name: string }): Promise<IBucketInfo | null>
+```
+
+Returns the bucket info from the full bucket list, or `null` if not found.
+
+#### createBucket
+
+```typescript
+async createBucket(opts: { name: string }): Promise<IBucketInfo | null>
+```
+
+Creates a bucket via a signed `PUT /{name}` request. Throws if the name fails validation or the S3 request fails.
+
+#### removeBucket
+
+```typescript
+async removeBucket(opts: { name: string }): Promise<boolean>
+```
+
+Removes a bucket via a signed `DELETE /{name}` request. Throws if the name fails validation or the S3 request fails.
+
+#### upload
+
+```typescript
+async upload(opts: {
+  bucket: string;
+  files: IUploadFile[];
+  normalizeNameFn?: (opts: { originalName: string; folderPath?: string }) => string;
+  normalizeLinkFn?: (opts: { bucketName: string; normalizeName: string }) => string;
+}): Promise<IUploadResult[]>
+```
+
+Uploads files using `client.write(name, buffer, { bucket, type })`. Same validation and normalization behavior as MinioHelper.
+
+**Default link format:** `/static-assets/{bucket}/{encodeURIComponent(normalizeName)}`
+
+#### getFile
+
+```typescript
+async getFile(opts: { bucket: string; name: string; options?: any }): Promise<Readable>
+```
+
+Returns a `Readable` stream by converting the Bun S3 file's web stream via `Readable.fromWeb()`.
+
+#### getStat
+
+```typescript
+async getStat(opts: { bucket: string; name: string }): Promise<IFileStat>
+```
+
+Returns file metadata via `client.stat()`.
+
+**Returns:**
+
+```typescript
+{
+  size: number;
+  lastModified: Date;
+  metadata: {
+    contentType: string;
+    mimetype: string;
+  };
+  etag: string;
+}
+```
+
+#### removeObject
+
+```typescript
+async removeObject(opts: { bucket: string; name: string }): Promise<void>
+```
+
+Removes a single object via `client.delete()`.
+
+#### removeObjects
+
+```typescript
+async removeObjects(opts: { bucket: string; names: string[] }): Promise<void>
+```
+
+Removes multiple objects in parallel via `Promise.all()`.
+
+#### listObjects
+
+```typescript
+async listObjects(opts: {
+  bucket: string;
+  prefix?: string;
+  useRecursive?: boolean;
+  maxKeys?: number;
+}): Promise<IObjectInfo[]>
+```
+
+Lists objects using `client.list()`. Returns objects with `name` (from `key`), `size`, `lastModified`, and `etag` (from `eTag`).
+
+> [!NOTE]
+> The `useRecursive` parameter is accepted for interface compatibility but is not used -- Bun's S3 `list()` does not support recursive mode directly.
+
 ## DiskHelper
 
 Local filesystem storage using directory-based buckets. Extends `BaseStorageHelper`.
@@ -574,7 +722,7 @@ Returns the underlying container object.
 
 ### IStorageHelper
 
-The unified interface implemented by `MinioHelper` and `DiskHelper`:
+The unified interface implemented by `MinioHelper`, `BunS3Helper`, and `DiskHelper`:
 
 ```typescript
 interface IStorageHelper {
@@ -698,8 +846,20 @@ interface IMinioHelperOptions extends IStorageHelperOptions, ClientOptions {}
 
 Inherits all `minio.ClientOptions` properties: `endPoint`, `port`, `useSSL`, `accessKey`, `secretKey`, `region`, `transport`, `sessionToken`, `partSize`, `pathStyle`, and others.
 
+### IBunS3HelperOptions
+
+```typescript
+interface IBunS3HelperOptions extends IStorageHelperOptions {
+  accessKey: string;
+  secretKey: string;
+  endpoint: string;
+  region?: string;         // Default: 'us-east-1'
+  sessionToken?: string;
+}
+```
+
 ## See Also
 
 - [Setup & Usage](./) -- Getting started, examples, and troubleshooting
 - [Helpers Index](../index) -- All available helpers
-- [Static Asset Component](/references/components/static-asset/) -- Serving stored files via HTTP
+- [Static Asset Component](/extensions/components/static-asset/) -- Serving stored files via HTTP