From eb014048c2f75addfb812e5099267a635331f67b Mon Sep 17 00:00:00 2001
From: Justin Mclean <justinmclean@apache.org>
Date: Thu, 1 Oct 2026 10:48:09 +1000
Subject: [PATCH] docs: add a consumer group sample to the Node quick start

Adds a runnable consumer group sample and says what each sample does when run again. Run against apache-iggy 0.10.0 and server 0.9.0.
---
 content/docs/sdk/node/intro.mdx | 53 ++++++++++++++++++++++++++++++++-
 1 file changed, 52 insertions(+), 1 deletion(-)

diff --git a/content/docs/sdk/node/intro.mdx b/content/docs/sdk/node/intro.mdx
index 5226b2eaab..ac200fc10f 100644
--- a/content/docs/sdk/node/intro.mdx
+++ b/content/docs/sdk/node/intro.mdx
@@ -32,7 +32,7 @@ cargo run --bin iggy-server -- --fresh --with-default-root-credentials
 
 The environment variables make the server reachable through the published port (it binds to `127.0.0.1` inside the container by default) and set the root credentials the samples log in with. Without `--with-default-root-credentials` (or the `IGGY_ROOT_USERNAME` / `IGGY_ROOT_PASSWORD` variables), a first boot generates a random root password instead of `iggy`/`iggy`. For source runs, `--fresh` deletes existing local server data. Explicit credential environment variables take precedence over the default-root flag; bootstrap settings do not replace credentials already stored in recovered data.
 
-Save the following snippets as `producer.mjs` and `consumer.mjs` in the project where you installed the SDK. Run `node producer.mjs` before `node consumer.mjs`.
+Save the following snippets as `producer.mjs` and `consumer.mjs` in the project where you installed the SDK. Run `node producer.mjs` before `node consumer.mjs`. A consumer group sample follows them.
 
 ### Producer
 
@@ -121,6 +121,57 @@ await client.destroy();
 
 The poll response does not wait for the auto-commit to finish. The sample processes messages after polling, so auto-commit does not confirm that the application handled each message.
 
+### Consumer group
+
+A consumer group lets several consumers share a topic. The server assigns partitions to the members and stores the group's offset. Save this as `consumer-group.mjs`:
+
+```typescript
+import { Client, PollingStrategy, Consumer } from 'apache-iggy';
+
+const STREAM_NAME = 'sample-stream';
+const TOPIC_NAME = 'sample-topic';
+const GROUP_NAME = 'sample-group';
+
+const client = new Client({
+  transport: 'TCP',
+  options: { port: 8090, host: '127.0.0.1' },
+  credentials: { username: 'iggy', password: 'iggy' },
+});
+
+// Creates the group if it is missing, then joins it.
+const group = await client.group.ensureAndJoin(STREAM_NAME, TOPIC_NAME, GROUP_NAME);
+
+// The server assigns partitions to each group member, so partitionId is null.
+const polledMessages = await client.message.poll({
+  streamId: STREAM_NAME,
+  topicId: TOPIC_NAME,
+  consumer: Consumer.Group(group.id),
+  partitionId: null,
+  pollingStrategy: PollingStrategy.Next,
+  count: 10,
+  autocommit: true,
+});
+
+for (const message of polledMessages.messages) {
+  const payload = message.payload.toString('utf8');
+  console.log(`Offset: ${message.headers.offset}, Payload: ${payload}`);
+}
+
+await client.destroy();
+```
+
+The group's offset is separate from the single consumer's, so the first run of `node consumer-group.mjs` reads the topic from offset 0 even after `consumer.mjs` has run.
+
+### Running the samples again
+
+All three samples can be run again without changes:
+
+- `node producer.mjs` finds the existing stream and topic and appends ten more messages.
+- `node consumer.mjs` prints only the new messages, because `PollingStrategy.Next` continues after the stored offset. With nothing new to read, it prints nothing.
+- `node consumer-group.mjs` does the same from the group's stored offset.
+
+To start again with an empty server, stop the container and run the `docker run` command again. `--rm` removes the container and its data.
+
 ## Configuration
 
 The client constructor accepts a few options: