@adobe-commerce/aio-toolkit 1.0.2 → 1.0.4

package/CHANGELOG.md

@@ -5,6 +5,117 @@ 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.0.4] - 2025-10-29
+
+### 🚀 Major Feature Release: Webhook Components & Shipping Carrier Builder
+
+This minor release introduces powerful new components for Adobe Commerce webhook extensibility, including a comprehensive ShippingCarrier builder and WebhookAction component with signature verification. These additions enable developers to easily create custom shipping carriers and handle webhook requests securely.
+
+#### 🎯 Commerce Components
+
+- **ShippingCarrier** `[New]` - Fluent builder for custom shipping carrier creation
+  - Builder pattern implementation with method chaining support
+  - Comprehensive carrier configuration (title, stores, countries, sort order, active status)
+  - Shipping method management with add/remove capabilities
+  - Validation for carrier and method codes (alphanumeric and underscores only)
+  - Integration with WebhookActionResponse for seamless webhook responses
+  - Type-safe TypeScript interfaces for all data structures
+  - 100% test coverage with 67 comprehensive tests
+
+- **ShippingCarrierMethod** `[New]` - Builder for individual shipping methods
+  - Configure method title, price, cost, and additional data
+  - Flexible additional data structure for custom metadata
+  - Returns structured method data via `getData()`
+  - Full TypeScript support with `ShippingCarrierMethodData` interface
+
+- **ShippingCarrierResponse** `[New]` - Webhook response generator
+  - Generates WebhookActionResponse operations from ShippingCarrier instances
+  - Handles both added and removed shipping methods
+  - Creates proper operation structures for Adobe Commerce webhook extensibility
+
+#### 🔧 Framework Components
+
+- **WebhookAction** `[New]` - Secure webhook request handler with signature verification
+  - Built-in Adobe Commerce webhook signature verification
+  - Configurable signature verification (enabled/disabled)
+  - Wrapper around RuntimeAction for consistent request handling
+  - Support for required parameters and headers validation
+  - Integration with WebhookActionResponse for structured responses
+  - Comprehensive error handling and logging
+
+- **WebhookActionResponse** `[New]` - Structured webhook response builder
+  - Success, exception, add, replace, and remove operations
+  - Type-safe response structures with TypeScript interfaces
+  - Compatible with Adobe Commerce webhook extensibility model
+  - Clean API for building complex webhook responses
+
+#### 🛠️ Repository Components
+
+- **FileRepository** `[Enhanced]` - File system timestamp integration
+  - Use file system properties for `createdAt` and `updatedAt` timestamps
+  - Retrieve timestamps using `files.getProperties()` method
+  - Timestamps reflect actual file system state
+  - Removed timestamps from file content for cleaner data storage
+  - Enhanced `metadata()` method for lightweight file listing without content
+
+- **FileRepository** `[Enhanced]` - Metadata method for efficient file listing
+  - New `metadata()` method for retrieving file properties without reading content
+  - Significantly faster than `list()` for large file sets
+  - Returns file size, creation time, and modification time
+  - Supports both single file and batch metadata retrieval
+
+- **FileRepository** `[Enhanced]` - Overwrite flag for controlled file writes
+  - New `overwrite` parameter in `save()` method
+  - Default behavior: merge with existing file (overwrite: false)
+  - Explicit overwrite: replace entire file (overwrite: true)
+  - Enhanced control over file update strategies
+
+## [1.0.3] - 2025-10-23
+
+### 🎨 New Experience Module & Enhanced Framework Components
+
+This patch release introduces a comprehensive new Experience module with AdminUiSdk for Adobe Commerce Admin UI extensions, enhanced IMS token caching with State library integration, Adobe I/O event publishing capabilities with CloudEvents compliance, and critical bug fixes for authentication endpoints. All changes maintain backward compatibility while adding powerful new functionality.
+
+#### 🎨 Experience Components
+
+- **AdminUiSdk** `[New]` - Adobe Commerce Admin UI extension management
+  - Create and manage menu items, sections, and page configurations programmatically
+  - Full namespaced ID support (e.g., `dataMappingTool::appBuilderApplication`)
+  - Parent-child menu relationships with external references (`Magento_Backend::system`)
+  - Comprehensive validation and error handling with detailed error messages
+  - Type-safe TypeScript interfaces for MenuItem, Page, and AdminUiSdkRegistration
+  - **BREAKING CHANGE**: Accepts full IDs without automatic prefixing for real-world usage patterns
+
+#### 🔧 Framework Components
+
+- **CustomLogger** `[New]` - Centralized null-safe logging utility
+  - Consistent logging interface with debug, info, and error methods across all components
+  - Graceful handling of missing or null logger instances without throwing errors
+  - Seamless integration with Adobe I/O Runtime logger
+
+- **PublishEvent** `[New]` - Adobe I/O Event Publishing with CloudEvents compliance
+  - CloudEvents specification compliance with proper event structure
+  - UUID generation for unique event tracking and correlation
+  - Comprehensive validation for IMS organization ID, API keys, and access tokens
+  - Integration with CustomLogger for consistent error handling and debugging
+  - Support for custom event subjects and structured payload data
+
+#### 🛠️ Commerce Components
+
+- **GenerateImsToken** `[Enhanced]` - IMS token caching using Adobe I/O State library
+  - Automatic token caching and refresh using Adobe I/O State library for performance optimization
+  - Token validation and automatic renewal before expiration
+  - Enhanced error handling and logging for token operations
+  - **BREAKING CHANGE**: ImsConnection constructor simplified - no longer requires currentContext parameter
+
+#### 🐛 Critical Bug Fixes
+
+- **BasicAuthConnection Token Endpoint Construction** `[Resolved]`
+  - **Problem**: Duplicate `/rest/rest/` segments in token endpoints for base URLs ending with '/rest'
+  - **Root Cause**: Improper URL concatenation when base URL already contained REST endpoint path
+  - **Solution**: Enhanced createTokenEndpoint() method with intelligent URL parsing and construction
+  - **Impact**: Correct token endpoint generation for all base URL formats, maintaining backward compatibility
+
 ## [1.0.2] - 2025-09-30
 
 ### 🛠️ Framework Component Enhancements & Critical Bug Fixes

package/README.md

@@ -2,7 +2,7 @@
 
 ## Overview
 
-A comprehensive TypeScript toolkit for Adobe App Builder applications providing standardized Adobe Commerce integrations, I/O Events orchestration, file storage utilities, authentication helpers, and robust backend development tools with 100% test coverage.
+A comprehensive TypeScript toolkit for Adobe App Builder applications providing standardized Adobe Commerce integrations, I/O Events orchestration, file storage utilities, authentication helpers, and robust backend development tools with 100% test coverage and enterprise-grade reliability.
 
 ## Installation
 
@@ -12,7 +12,7 @@ npm install @adobe-commerce/aio-toolkit
 
 ## Usage
 
-The toolkit is organized into four main modules:
+The toolkit is organized into five main modules:
 
 ### 🛠️ Framework Components
 
@@ -91,6 +91,112 @@ const myEventConsumer = EventConsumerAction.execute(
 exports.main = myEventConsumer;
 ```
 
+#### `WebhookAction`
+Secure webhook request handler with built-in Adobe Commerce signature verification.
+
+```typescript
+const { 
+  WebhookAction,
+  WebhookActionResponse,
+  SignatureVerification
+} = require('@adobe-commerce/aio-toolkit');
+
+// Create a webhook action with signature verification enabled
+const myWebhook = WebhookAction.execute(
+  'order-webhook',
+  ['orderId'], // Required parameters
+  ['x-adobe-commerce-webhook-id'], // Required headers
+  SignatureVerification.ENABLED, // Enable signature verification
+  async (params, ctx) => {
+    const { orderId } = params;
+    const { logger } = ctx;
+
+    logger.info(`Processing order webhook: ${orderId}`);
+
+    // Your webhook logic here
+    // Return structured webhook response
+    return [
+      WebhookActionResponse.add('result', {
+        orderId: orderId,
+        status: 'processed',
+        timestamp: new Date().toISOString()
+      }),
+      WebhookActionResponse.success()
+    ];
+  }
+);
+
+// Export for Adobe I/O Runtime
+exports.main = myWebhook;
+
+// Disable signature verification for testing
+const testWebhook = WebhookAction.execute(
+  'test-webhook',
+  ['data'],
+  [],
+  SignatureVerification.DISABLED,
+  async (params, ctx) => {
+    return WebhookActionResponse.success();
+  }
+);
+```
+
+**WebhookActionResponse Operations:**
+- `success()`: Indicates successful webhook processing
+- `exception(message?, exceptionClass?)`: Returns error response
+- `add(path, value, instance?)`: Adds data to response
+- `replace(path, value, instance?)`: Replaces data in response
+- `remove(path)`: Removes data from response
+
+#### `PublishEvent`
+Event publishing component for Adobe I/O Events with CloudEvents support.
+
+```typescript
+const { PublishEvent } = require('@adobe-commerce/aio-toolkit');
+
+// Initialize the publisher
+const publishEvent = new PublishEvent(
+  'your-ims-org-id@AdobeOrg',
+  'your-api-key',
+  'your-access-token',
+  logger // Optional custom logger
+);
+
+// Publish a simple event
+const result = await publishEvent.execute(
+  'your-provider-id',
+  'commerce.order.created',
+  {
+    orderId: 'ORD-123456',
+    customerId: 'CUST-789',
+    amount: 199.99,
+    currency: 'USD'
+  }
+);
+
+console.log(`Event published: ${result.eventId}, Status: ${result.status}`);
+
+// Publish an event with subject
+const orderResult = await publishEvent.execute(
+  'commerce-provider',
+  'com.adobe.commerce.order.shipped',
+  {
+    orderId: 'ORD-123456',
+    trackingNumber: 'TRK-789',
+    carrier: 'UPS',
+    estimatedDelivery: '2023-12-05T18:00:00Z'
+  },
+  'orders/ORD-123456'
+);
+
+// Handle publishing results
+if (orderResult.status === 'published') {
+  console.log(`Order shipped event published successfully: ${orderResult.eventId}`);
+} else {
+  console.error(`Failed to publish event: ${orderResult.error}`);
+}
+```
+
 #### `GraphQlAction`
 GraphQL server implementation with schema validation and introspection control.
 
@@ -180,11 +286,17 @@ exports.main = helloWorldAction;
 File-based storage with CRUD operations for Adobe I/O Runtime applications.
 
 **Key Methods:**
-- `save(payload, id?)`: Saves data with optional ID parameter. The `id` parameter takes precedence over `payload.id`. IDs are automatically sanitized to alphanumeric + underscore characters.
-- `load(id)`: Loads data by ID
-- `list()`: Lists all stored records
+- `save(payload, id?, overwrite?)`: Saves data with optional ID parameter and overwrite flag. The `id` parameter takes precedence over `payload.id`. IDs are automatically sanitized to alphanumeric + underscore characters. Set `overwrite: true` to replace entire file, or `false` (default) to merge with existing data.
+- `load(id)`: Loads data by ID with file system timestamps (`createdAt`, `updatedAt`)
+- `list()`: Lists all stored records with file system timestamps
+- `metadata(id?)`: Retrieves file metadata (size, timestamps) without reading content - faster than `list()` for large datasets
 - `delete(ids)`: Deletes records by ID array
 
+**New in v1.0.4:**
+- **File System Timestamps**: `createdAt` and `updatedAt` are now retrieved from actual file system properties instead of being stored in file content
+- **Metadata Method**: New `metadata()` method for efficient file property retrieval without reading file content
+- **Overwrite Flag**: Control file update strategy with `save(payload, id, overwrite)` - merge (default) or replace entire file
+
 **Best Practice:** Create custom repository classes that extend FileRepository for specific entities.
 
 ##### **1. Define Entity Repository**
@@ -283,7 +395,69 @@ exports.main = RuntimeAction.execute(
 );
 ```
 
-##### **5. Delete Action**
+##### **5. Save with Overwrite Flag**
+Control file update strategy with the overwrite parameter:
+
+```javascript
+const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
+const EntityRepository = require("@lib/EntityRepository");
+
+exports.main = RuntimeAction.execute(
+    "entity-save-overwrite",
+    [HttpMethod.POST],
+    ['name', 'status'],
+    ['Authorization'],
+    async (params) => {
+        const entityRepository = new EntityRepository();
+
+        const payload = {
+            name: params.name,
+            status: params.status
+        };
+
+        // Replace entire file instead of merging
+        const savedId = await entityRepository.save(payload, params.id, true);
+
+        return RuntimeActionResponse.success({
+            id: savedId,
+            message: 'Entity replaced successfully'
+        });
+    }
+);
+```
+
+##### **6. Metadata Action**
+Retrieve file metadata without reading content (faster for large datasets):
+
+```javascript
+const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
+const EntityRepository = require("@lib/EntityRepository");
+
+exports.main = RuntimeAction.execute(
+    "entity-metadata",
+    [HttpMethod.POST],
+    [],
+    ['Authorization'],
+    async (params) => {
+        const entityRepository = new EntityRepository();
+        
+        // Get metadata for all files
+        const allMetadata = await entityRepository.metadata();
+        
+        // Or get metadata for specific file
+        const singleMetadata = params.id 
+            ? await entityRepository.metadata(params.id)
+            : null;
+
+        return RuntimeActionResponse.success({
+            all: allMetadata,
+            single: singleMetadata
+        });
+    }
+);
+```
+
+##### **7. Delete Action**
 Delete entities by providing an array of IDs:
 
 ```javascript
@@ -336,24 +510,188 @@ console.log('Authentication token:', token);
 #### `AdobeCommerceClient`
 HTTP client for Adobe Commerce API integration with multiple authentication methods.
 
+**OAuth 1.0a Authentication**
 ```typescript
-const { AdobeCommerceClient } = require('@adobe-commerce/aio-toolkit');
-const { Oauth1aConnection } = require('@adobe-commerce/aio-toolkit');
+const { AdobeCommerceClient, Oauth1aConnection } = require('@adobe-commerce/aio-toolkit');
 
 const connection = new Oauth1aConnection(
   'consumer-key',
   'consumer-secret',
   'access-token',
   'access-token-secret',
-  logger? // Optional custom logger
+  logger // Optional custom logger
 );
 
 // Create client
+const client = new AdobeCommerceClient('https://your-commerce-store.com/rest', connection);
+
+// Make API calls
+const products = await client.get('V1/products');
+const newProduct = await client.post('V1/products', {}, productData);
+```
+
+**IMS (Identity Management System) Authentication**
+```typescript
+const { AdobeCommerceClient, ImsConnection } = require('@adobe-commerce/aio-toolkit');
+
+const connection = new ImsConnection(
+  'client-id',
+  'client-secret', 
+  'technical-account-id',
+  'technical-account-email',
+  'ims-org-id',
+  ['AdobeID', 'openid', 'adobeio_api'], // Scopes array
+  logger // Optional custom logger
+);
+
+// Create client with IMS authentication
 const client = new AdobeCommerceClient('https://your-commerce-store.com', connection);
 
+// Make API calls - tokens are automatically cached and refreshed
+const products = await client.get('V1/products');
+const newProduct = await client.post('V1/products', {}, productData);
+```
+
+**Enhanced IMS Token Caching**
+
+```typescript
+const { GenerateImsToken } = require('@adobe-commerce/aio-toolkit');
+
+const tokenGenerator = new GenerateImsToken(
+  'client-id', 'client-secret', 'technical-account-id',
+  'technical-account-email', 'ims-org-id',
+  ['AdobeID', 'openid', 'adobeio_api'], logger
+);
+
+const token = await tokenGenerator.execute();
+```
+
+**Basic Authentication**
+```typescript
+const { AdobeCommerceClient, BasicAuthConnection } = require('@adobe-commerce/aio-toolkit');
+
+const connection = new BasicAuthConnection(
+  'username',
+  'password',
+  logger // Optional custom logger
+);
+
+// Create client
+const client = new AdobeCommerceClient('https://your-commerce-store.com/rest', connection);
+
 // Make API calls
-const products = await client.get('rest/V1/products');
-const newProduct = await client.post('rest/V1/products', {}, productData);
+const products = await client.get('V1/products');
+```
+
+#### `ShippingCarrier`
+Fluent builder for creating custom shipping carriers for Adobe Commerce webhook extensibility.
+
+```typescript
+const { 
+  ShippingCarrier,
+  ShippingCarrierResponse
+} = require('@adobe-commerce/aio-toolkit');
+
+// Create a custom shipping carrier with methods
+const carrier = new ShippingCarrier('fedex', (carrier) => {
+  carrier
+    .setTitle('FedEx Express')
+    .setStores(['default', 'store1'])
+    .setCountries(['US', 'CA', 'MX'])
+    .setSortOrder(10)
+    .setActive(true)
+    .setTrackingAvailable(true)
+    .setShippingLabelsAvailable(true)
+    .addMethod('standard', (method) => {
+      method
+        .setMethodTitle('Standard Shipping')
+        .setPrice(9.99)
+        .setCost(5.00)
+        .addAdditionalData('delivery_time', '3-5 business days')
+        .addAdditionalData('tracking_available', true);
+    })
+    .addMethod('express', (method) => {
+      method
+        .setMethodTitle('Express Shipping')
+        .setPrice(19.99)
+        .setCost(12.00)
+        .addAdditionalData('delivery_time', '1-2 business days');
+    })
+    .removeMethod('overnight'); // Remove a method
+});
+
+// Get carrier configuration
+const carrierData = carrier.getData();
+console.log(carrierData);
+
+// Generate webhook response operations
+const response = new ShippingCarrierResponse(carrier);
+const operations = response.generate();
+return operations; // Use in webhook action
+
+carrier.setData({
+  code: 'dps',
+  title: 'Demo Postal Service',
+  stores: ['default'],
+  countries: ['US', 'CA'],
+  sort_order: 10,
+  active: true,
+  tracking_available: true,
+  shipping_labels_available: true
+});
+
+// Reset carrier with new code
+carrier.reset('ups', (c) => {
+  c.addMethod('ground', (m) => {
+    m.setMethodTitle('UPS Ground').setPrice(12.99);
+  });
+});
+```
+
+**Key Features:**
+- Builder pattern with method chaining
+- Validation for carrier and method codes (alphanumeric and underscores only)
+- Add and remove shipping methods dynamically
+- Configure carrier properties (title, stores, countries, sort order, etc.)
+- Generate webhook response operations
+- Type-safe TypeScript interfaces
+
+**Validation Rules:**
+- Carrier and method codes must contain only alphanumeric characters and underscores
+- No spaces, hyphens, dots, or special characters allowed
+- Empty or whitespace-only codes throw errors
+
+### 🎨 Experience Components
+
+**Adobe Commerce Admin UI extension and user experience tools**
+
+#### `AdminUiSdk`
+Create and manage Adobe Commerce Admin UI extensions with menu items, sections, and page configurations.
+
+```typescript
+const { AdminUiSdk } = require('@adobe-commerce/aio-toolkit');
+
+const sdk = new AdminUiSdk('dataMappingTool');
+
+// Add menu section with external parent
+sdk.addMenuSection(
+  'dataMappingTool::checkout_integration',
+  'Checkout Integration',
+  100,
+  'Magento_Backend::system'
+);
+
+// Add menu item
+sdk.addMenuItem(
+  'dataMappingTool::application',
+  'Application',
+  1,
+  'dataMappingTool::checkout_integration'
+);
+
+// Set page title and get registration
+sdk.addPage('Data Mapping Tool Dashboard');
+const registration = sdk.getRegistration();
 ```
 
 ### 🔗 Integration Components