@adobe-commerce/aio-toolkit 1.2.3 → 1.2.4

package/CHANGELOG.md

@@ -5,6 +5,87 @@ 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

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
@@ -1509,7 +1550,7 @@ if (directInfo.isValid) {
 - `info(token)` - Analyzes token string and returns validation/expiry details
 
 #### `RabbitMQClient`
-Push-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.
+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
@@ -1578,7 +1619,7 @@ if (stats.errors.length) {
 
 | Method | Description | Returns |
 |---|---|---|
-| `consume(queueName, options, handler)` | Checks queue depth, sets prefetch, and push-consumes up to `batchSize` messages | `Promise<ConsumeStats>` |
+| `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`**
@@ -1586,7 +1627,7 @@ if (stats.errors.length) {
 | Field | Type | Required | Description |
 |---|---|---|---|
 | `batchSize` | `number` | ✅ | Maximum number of messages to process in this call |
-| `maxParallel` | `number` | ✅ | Max unacked messages in-flight at once (broker-side prefetch) |
+| `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 |
 
@@ -1605,7 +1646,7 @@ if (stats.errors.length) {
 |---|---|---|
 | `published` | `number` | Messages successfully enqueued |
 | `failed` | `number` | Messages that could not be enqueued |
-| `errors` | `Array<{ payload: string; error: unknown }>` | Per-failure details (buffer full or thrown) |
+| `errors` | `Array<{ payload: string; error: unknown }>` | Per-failure details (thrown errors only; write-buffer-full is handled via backpressure) |
 
 ---