@adobe-commerce/aio-toolkit 1.2.2 → 1.2.4

package/CHANGELOG.md

@@ -5,6 +5,142 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.4] - 2026-04-20
+
+### ✨ Features
+
+- **feat(repository): Add pagination and sort options to `AbdbRepository.find`**
+
+  `find` now accepts an optional second parameter `options: AbdbFindOptions` for
+  server-side pagination and sorting, applied via the MongoDB cursor chain:
+  `.sort(...)` → `.skip(...)` → `.limit(...)`.
+
+  ```typescript
+  // Page 2, 20 per page, newest first
+  await repo.find(
+    { active: true },
+    { current_page: 2, page_size: 20, sort: { column: '_created_at', direction: 'desc' } }
+  );
+  ```
+
+  **`AbdbFindOptions` fields (all optional):**
+  | Field | Type | Description |
+  |---|---|---|
+  | `sort` | `AbdbFindSort` | `{ column: string; direction?: 'asc' \| 'desc' }` — direction defaults to `'asc'` |
+  | `page_size` | `number` | Maximum documents to return; enables `.limit()` |
+  | `current_page` | `number` | 1-based page index; combined with `page_size` to compute `.skip()`. Page 1 skips the `.skip()` call. |
+
+  Calling `find` without options is fully backward compatible — no sort, skip, or limit is applied.
+
+  **New exported types:** `AbdbFindOptions`, `AbdbFindSort`, `AbdbFindSortDirection`
+
+- **feat(integration): Refactor `RabbitMQClient` from push-based to pull-based consumption**
+
+  `RabbitMQClient.consume` now uses `channel.get` (AMQP `basic.get`) instead of
+  `channel.consume` (push subscription). This makes batch termination fully deterministic —
+  `channel.get` returns `false` immediately when the queue is empty, so there is no consumer
+  tag to cancel, no cancellation race condition, and no activation-timeout hang.
+
+  **What changed:**
+  - `processBatch` rewritten: windowed `Promise.all(maxParallel)` replaces `channel.prefetch` +
+    `channel.consume`. Each window pulls up to `maxParallel` messages sequentially via
+    `channel.get`, then processes them concurrently before moving to the next window.
+  - `publish` backpressure improved: `sendToQueue` returning `false` (write buffer full) now
+    counts the message as published and waits for the channel's `drain` event before
+    continuing. Previously, a full buffer was counted as a failure.
+  - `finally` blocks in `consume` and `publish` now wrap `channel.close()` in a try/catch so
+    a close error never prevents the connection from closing.
+
+  **No API changes** — `consume(queueName, options, handler)` and `publish(queueName, payloads)`
+  signatures, `RabbitMQConsumeOptions`, `ConsumeStats`, and `PublishStats` are unchanged.
+
+### 🐛 Bug Fixes
+
+- **fix(webhook-action): Rename `WebhookActionExceptionResponse.class` → `type`**
+
+  Adobe Commerce webhooks expect `"type"` in the exception response payload,
+  not `"class"`. The previous field name was silently sending the wrong key,
+  causing an **Internal Server Error** instead of the intended exception
+  (e.g. `GraphQlInputException`).
+
+  **Before (broken):**
+  ```typescript
+  WebhookActionResponse.exception(
+    'Lease term not available for this cart',
+    'Magento\\Framework\\GraphQl\\Exception\\GraphQlInputException'
+  );
+  // sent: { "op": "exception", "class": "...", "message": "..." }  ❌
+  ```
+
+  **After (correct):**
+  ```typescript
+  WebhookActionResponse.exception(
+    'Lease term not available for this cart',
+    'Magento\\Framework\\GraphQl\\Exception\\GraphQlInputException'
+  );
+  // sent: { "op": "exception", "type": "...", "message": "..." }  ✅
+  ```
+
+  **Migration:** Replace any direct use of the `class` field on
+  `WebhookActionExceptionResponse` with `type`.
+
+---
+
+## [1.2.3] - 2026-04-01
+
+### ✨ Features
+
+- **feat(integration): Add `RabbitMQClient` — push-based AMQP consumer and publisher**
+
+  New `RabbitMQClient` class in `src/integration/rabbit-mq-client` provides a
+  clean, typed interface for consuming and publishing messages via AMQP (RabbitMQ).
+
+  **`consume(queueName, options, handler)`**
+  - Checks queue depth via `channel.checkQueue` — skips immediately when empty
+  - Sets `channel.prefetch(maxParallel)` for broker-side concurrency control
+  - Processes `effectiveBatch = min(batchSize, messageCount)` messages
+  - Acks on successful handler execution; nacks on failure (requeue configurable)
+  - Optional exchange assertion and queue binding via `options.exchange`
+  - Returns `ConsumeStats` — consumed, acked, nacked counts plus per-failure details
+
+  **`publish(queueName, payloads)`**
+  - Asserts queue and sends each payload via `sendToQueue` with `persistent: true`
+  - Records write-buffer-full (`sendToQueue` returns `false`) and thrown errors
+  - Returns `PublishStats` — published and failed counts plus per-failure details
+
+  Both methods open a dedicated connection per call and always close channel and
+  connection in a `finally` block.
+
+  **Exported types** (from `rabbit-mq-client/types`):
+  `RabbitMQCredentials`, `RabbitMQConsumeOptions`, `MessageHandler`,
+  `ConsumeStats`, `PublishStats`
+
+  **Note:** `batchSize` and `maxParallel` are required in `RabbitMQConsumeOptions`
+  — the caller must choose appropriate limits for their workload.
+
+### 🐛 Bug Fixes
+
+- **fix(abdb): Preserve `error.cause` on `AbdbCollection` thrown errors**
+
+  `run()` now assigns `.cause` to each re-thrown `Error` so callers can access
+  the original error via `err.cause`. Previously the root cause was silently
+  discarded. Assignment is done via `(err as any).cause` for compatibility with
+  the ES2020 TypeScript target (the ES2022 `Error(msg, { cause })` constructor
+  overload is not available in ES2020 lib typings).
+
+- **fix(abdb): Guard `DbError instanceof` check against undefined export**
+
+  The `DbError` branch now uses `DbError && error instanceof DbError` so the
+  code does not throw a `TypeError` in environments where `@adobe/aio-lib-db`
+  does not export `DbError` at runtime. Unrecognised errors fall through to the
+  `unexpected error` path as expected.
+
+- **fix(abdb): Correct file header comment in `adobe-aio-lib-db.d.ts`**
+
+  The comment incorrectly read `@adobe/aio-lib-ims`; updated to `@adobe/aio-lib-db`.
+
+---
+
 ## [1.2.2] - 2026-04-01
 
 ### 🐛 Bug Fixes

package/README.md

@@ -151,11 +151,21 @@ const testWebhook = WebhookAction.execute(
 
 **WebhookActionResponse Operations:**
 - `success()`: Indicates successful webhook processing
-- `exception(message?, exceptionClass?)`: Returns error response
+- `exception(message?, exceptionType?)`: Returns error response with an optional Magento exception type (e.g. `'Magento\\Framework\\GraphQl\\Exception\\GraphQlInputException'`)
 - `add(path, value, instance?)`: Adds data to response
 - `replace(path, value, instance?)`: Replaces data in response
 - `remove(path)`: Removes data from response
 
+**Exception response example:**
+```typescript
+// Return a typed Magento exception — Commerce will surface it as a proper error
+return WebhookActionResponse.exception(
+  'Lease term not available for this cart',
+  'Magento\\Framework\\GraphQl\\Exception\\GraphQlInputException'
+);
+// Produces: { "op": "exception", "type": "Magento\\...", "message": "..." }
+```
+
 #### `PublishEvent`
 Event publishing component for Adobe I/O Events with CloudEvents support.
 
@@ -868,9 +878,10 @@ exports.main = async (params) => {
   // Read one by any field
   const byEmail = await repo.findOne({ email: 'jane@example.com' });
 
-  // Read all (optional filter)
+  // Read all (optional filter + optional pagination/sort)
   const all    = await repo.find();
   const active = await repo.find({ active: true });
+  const paged  = await repo.find({ active: true }, { current_page: 2, page_size: 20, sort: { column: '_created_at', direction: 'desc' } });
 
   // Partial update — only provided fields are validated; required fields already in the DB are not re-checked
   await repo.save({ first_name: 'Janet' }, id);
@@ -903,7 +914,7 @@ These are added once per collection instance, so re-using the same collection ac
 | `updateOne(payload, filter?, options?)` | Single-document update via `{ $set: payload }` (partial validation, stamps `_updated_at`) | `Promise<Record<string, any>>` — raw `updateOne` result (e.g. `modifiedCount`) |
 | `findOne(filter)` | First document matching filter, e.g. `{ email: 'a@b.com' }` | `Promise<T \| null>` |
 | `findById(id)` | Shorthand for `findOne({ _id: new ObjectId(id) })` | `Promise<T \| null>` |
-| `find(filter?)` | All documents matching filter (default: all) | `Promise<T[]>` |
+| `find(filter?, options?)` | All documents matching filter with optional pagination and sort (`AbdbFindOptions`) | `Promise<T[]>` |
 | `isIdExists(id)` | Returns `true` if a document with the given `_id` exists (no-op for empty id) | `Promise<boolean>` |
 | `exists(filter?, options?)` | Returns `true` if any document matching `filter` exists via `countDocuments` | `Promise<boolean>` |
 | `deleteOne(filter?)` | Delete first matching document via `deleteOne` | `Promise<Record<string, any>>` — raw `deleteOne` result |
@@ -925,6 +936,36 @@ These are added once per collection instance, so re-using the same collection ac
 | `getName()` | Returns the underlying collection name |
 | `getCollection()` | Returns the underlying `AbdbCollection` instance |
 
+##### Pagination and sorting
+
+`find` accepts an optional second argument for server-side pagination and sorting:
+
+```javascript
+// All active users, newest first
+const all = await repo.find(
+  { active: true },
+  { sort: { column: '_created_at', direction: 'desc' } }
+);
+
+// Page 2, 20 results per page, sorted ascending by name
+const page2 = await repo.find(
+  {},
+  { current_page: 2, page_size: 20, sort: { column: 'name', direction: 'asc' } }
+);
+
+// Just limit — no pagination offset
+const top10 = await repo.find({}, { page_size: 10 });
+```
+
+`AbdbFindOptions` fields (all optional):
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `sort.column` | `string` | — | Field to sort by |
+| `sort.direction` | `'asc' \| 'desc'` | `'asc'` | Sort direction |
+| `page_size` | `number` | — | Max documents to return (enables `.limit()`) |
+| `current_page` | `number` | — | 1-based page index; computes `.skip((page-1) * page_size)` |
+
 ##### Custom region
 
 ```javascript
@@ -1508,6 +1549,107 @@ if (directInfo.isValid) {
 - `extract(headersOrParams)` - Extracts Bearer token from headers or OpenWhisk params
 - `info(token)` - Analyzes token string and returns validation/expiry details
 
+#### `RabbitMQClient`
+Pull-based AMQP consumer and publisher for RabbitMQ. Manages the full connection lifecycle per call (connect → channel → close) and exposes a clean, typed interface without exposing raw AMQP primitives to the caller.
+
+**Installation**
+```bash
+npm install amqplib
+```
+
+**Basic Usage**
+```typescript
+const { RabbitMQClient } = require('@adobe-commerce/aio-toolkit');
+
+const client = new RabbitMQClient({
+  host: 'rabbitmq.example.com',
+  port: '5672',
+  username: 'user',
+  password: 'secret',
+  vhost: '/',
+  secure: false, // set true to use amqps://
+});
+```
+
+**Consuming messages**
+```typescript
+const stats = await client.consume(
+  'orders-queue',
+  { batchSize: 100, maxParallel: 10 },
+  async (queueName, content) => {
+    const order = JSON.parse(content);
+    await processOrder(order);
+  }
+);
+
+console.log(`consumed=${stats.consumed} acked=${stats.acked} nacked=${stats.nacked}`);
+if (stats.errors.length) {
+  console.error('Failed messages:', stats.errors);
+}
+```
+
+**Consuming with exchange binding**
+```typescript
+const stats = await client.consume(
+  'orders-queue',
+  {
+    batchSize: 50,
+    maxParallel: 5,
+    exchange: 'orders-exchange', // asserts exchange + binds queue before consuming
+    nackRequeue: false,          // dead-letter failed messages instead of requeueing
+  },
+  async (queueName, content) => {
+    await processOrder(JSON.parse(content));
+  }
+);
+```
+
+**Publishing messages**
+```typescript
+const payloads = orders.map(o => JSON.stringify(o));
+const stats = await client.publish('orders-queue', payloads);
+
+console.log(`published=${stats.published} failed=${stats.failed}`);
+if (stats.errors.length) {
+  console.error('Failed payloads:', stats.errors);
+}
+```
+
+**API Reference**
+
+| Method | Description | Returns |
+|---|---|---|
+| `consume(queueName, options, handler)` | Checks queue depth and pull-consumes up to `batchSize` messages via `channel.get` in parallel windows of `maxParallel` | `Promise<ConsumeStats>` |
+| `publish(queueName, payloads)` | Asserts queue and enqueues each payload as a persistent message | `Promise<PublishStats>` |
+
+**`RabbitMQConsumeOptions`**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `batchSize` | `number` | ✅ | Maximum number of messages to process in this call |
+| `maxParallel` | `number` | ✅ | Max messages processed concurrently per window (client-side) |
+| `nackRequeue` | `boolean` | — | Requeue on nack (default: `true`) |
+| `exchange` | `string` | — | If set, asserts a `direct` exchange and binds the queue before consuming |
+
+**`ConsumeStats`**
+
+| Field | Type | Description |
+|---|---|---|
+| `consumed` | `number` | Total messages received from the broker |
+| `acked` | `number` | Messages successfully processed and acked |
+| `nacked` | `number` | Messages that failed handler and were nacked |
+| `errors` | `Array<{ content: string; error: unknown }>` | Per-failure details |
+
+**`PublishStats`**
+
+| Field | Type | Description |
+|---|---|---|
+| `published` | `number` | Messages successfully enqueued |
+| `failed` | `number` | Messages that could not be enqueued |
+| `errors` | `Array<{ payload: string; error: unknown }>` | Per-failure details (thrown errors only; write-buffer-full is handled via backpressure) |
+
+---
+
 #### `InfiniteLoopBreaker`
 Detect and prevent infinite loops in event-driven applications.