@adobe-commerce/aio-toolkit 1.0.3 → 1.0.5

package/CHANGELOG.md

@@ -5,6 +5,116 @@ 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.5] - 2025-11-03
+
+### 🚀 API Enhancements, Security & Developer Experience Improvements
+
+This release focuses on improving security testing capabilities, refactoring
+logging for consistency, enhancing repository metadata, and improving the
+ShippingCarrier API for better developer experience and safety. All changes
+maintain backward compatibility except for the ShippingCarrier reset() method
+removal.
+
+#### 🔧 Commerce Components
+
+- **AdobeCommerceClient** `[Enhanced]` - HTTPS configuration support for
+  testing
+  - Added optional `httpsOptions` parameter to constructor
+  - Support for `rejectUnauthorized: false` for self-signed certificates
+  - Enables testing against local/staging environments with insecure SSL
+  - Options passed directly to `got` library's https configuration
+  - Fully backward compatible - parameter is optional
+
+- **AdobeCommerceClient, BasicAuthConnection, Oauth1aConnection** `[Refactored]`
+  - Logger initialization refactored to use CustomLogger
+  - Consistent null-safe logging across all commerce client classes
+  - Removed direct dependency on Core.Logger from @adobe/aio-sdk
+  - Simplified constructor logic with centralized logging
+  - Enhanced CustomLogger with variadic argument support for logging methods
+
+- **ShippingCarrier** `[Breaking Change]` - Removed reset() method and
+  immutable code property
+  - **BREAKING**: Removed `reset()` method - users should create new
+    ShippingCarrier instances
+  - Made `code` property immutable in `setData()` method
+  - Code is now preserved across all `setData()` calls
+  - Prevents accidental override of carrier identity
+  - Added `getAddedMethods()` public getter method
+  - Added `getRemovedMethods()` public getter method
+  - Better encapsulation with controlled access to method tracking arrays
+
+#### 🛠️ Framework Components
+
+- **CustomLogger** `[Enhanced]` - Variadic argument support
+  - Updated `debug()`, `info()`, and `error()` methods to accept variadic args
+  - Supports modern logging patterns like `logger.debug('User %s logged in', userId)`
+  - Full backward compatibility maintained
+
+## [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

package/README.md

@@ -91,6 +91,63 @@ 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.
 
@@ -229,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**
@@ -332,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
@@ -458,6 +583,92 @@ const client = new AdobeCommerceClient('https://your-commerce-store.com/rest', c
 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);
+
+// Access added and removed methods
+const addedMethods = carrier.getAddedMethods();   // ['standard', 'express']
+const removedMethods = carrier.getRemovedMethods(); // ['overnight']
+
+// Generate webhook response operations
+const response = new ShippingCarrierResponse(carrier);
+const operations = response.generate();
+return operations; // Use in webhook action
+
+// Update carrier data (code is immutable)
+carrier.setData({
+  code: 'ups', // This will be ignored - code remains 'fedex'
+  title: 'Demo Postal Service',
+  stores: ['default'],
+  countries: ['US', 'CA'],
+  sort_order: 10,
+  active: true,
+  tracking_available: true,
+  shipping_labels_available: true
+});
+
+// Code property is immutable - create new instance if you need different code
+const newCarrier = new ShippingCarrier('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.)
+- **Immutable code property** - prevents accidental carrier identity changes
+- Public getter methods: `getAddedMethods()` and `getRemovedMethods()`
+- 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
+- Code property cannot be changed after initialization
+
 ### 🎨 Experience Components
 
 **Adobe Commerce Admin UI extension and user experience tools**

package/dist/index.d.mts

@@ -126,14 +126,26 @@ interface FileRecord {
     updatedAt: string;
     [key: string]: any;
 }
+interface FileMetadata {
+    name: string;
+    creationTime: Date;
+    lastModified: Date;
+    etag: string;
+    contentLength: number;
+    contentType: string;
+    isDirectory: boolean;
+    isPublic: boolean;
+    url: string;
+}
 
 declare class FileRepository {
     private readonly filepath;
     private files;
     constructor(filepath: string);
     list(): Promise<FileRecord[]>;
+    metadata(id?: string): Promise<FileMetadata | FileMetadata[]>;
     load(id?: string): Promise<FileRecord>;
-    save(payload?: Partial<FileRecord>, id?: string | null): Promise<string | null>;
+    save(payload?: Partial<FileRecord>, id?: string | null, overwrite?: boolean): Promise<string | null>;
     delete(ids?: string[]): Promise<FileRecord[]>;
     private sanitizeFileId;
     private getFiles;
@@ -160,6 +172,65 @@ declare class PublishEvent {
     execute(providerId: string, eventCode: string, payload: any, subject?: string): Promise<PublishEventResult>;
 }
 
+declare enum WebhookActionOperation {
+    SUCCESS = "success",
+    EXCEPTION = "exception",
+    ADD = "add",
+    REPLACE = "replace",
+    REMOVE = "remove"
+}
+interface WebhookActionSuccessResponse {
+    op: typeof WebhookActionOperation.SUCCESS;
+}
+interface WebhookActionExceptionResponse {
+    op: typeof WebhookActionOperation.EXCEPTION;
+    class?: string;
+    message?: string;
+}
+interface WebhookActionAddResponse {
+    op: typeof WebhookActionOperation.ADD;
+    path: string;
+    value: any;
+    instance?: string;
+}
+interface WebhookActionReplaceResponse {
+    op: typeof WebhookActionOperation.REPLACE;
+    path: string;
+    value: any;
+    instance?: string;
+}
+interface WebhookActionRemoveResponse {
+    op: typeof WebhookActionOperation.REMOVE;
+    path: string;
+}
+type WebhookActionResponseType = WebhookActionSuccessResponse | WebhookActionExceptionResponse | WebhookActionAddResponse | WebhookActionReplaceResponse | WebhookActionRemoveResponse;
+
+declare enum SignatureVerification {
+    ENABLED = "enabled",
+    DISABLED = "disabled"
+}
+
+declare class WebhookAction {
+    static execute(name?: string, requiredParams?: string[], requiredHeaders?: string[], signatureVerification?: SignatureVerification, action?: (params: {
+        [key: string]: any;
+    }, ctx: {
+        logger: any;
+        headers: {
+            [key: string]: any;
+        };
+    }) => Promise<WebhookActionResponseType | WebhookActionResponseType[]>): (params: {
+        [key: string]: any;
+    }) => Promise<RuntimeActionResponseType>;
+}
+
+declare class WebhookActionResponse {
+    static success(): WebhookActionSuccessResponse;
+    static exception(message?: string, exceptionClass?: string): WebhookActionExceptionResponse;
+    static add(path: string, value: any, instance?: string): WebhookActionAddResponse;
+    static replace(path: string, value: any, instance?: string): WebhookActionReplaceResponse;
+    static remove(path: string): WebhookActionRemoveResponse;
+}
+
 interface BearerTokenInfo {
     token: string | null;
     tokenLength: number;
@@ -382,12 +453,17 @@ interface Connection {
 interface ExtendedRequestError extends RequestError {
     responseBody?: any;
 }
+interface HttpsOptions {
+    rejectUnauthorized?: boolean;
+    [key: string]: any;
+}
 
 declare class AdobeCommerceClient {
     private baseUrl;
     private connection;
     private logger;
-    constructor(baseUrl: string, connection: Connection, logger?: any);
+    private httpsOptions;
+    constructor(baseUrl: string, connection: Connection, logger?: any, httpsOptions?: HttpsOptions);
     get(endpoint: string, headers?: Record<string, string>): Promise<any>;
     post(endpoint: string, headers?: Record<string, string>, payload?: any): Promise<any>;
     put(endpoint: string, headers?: Record<string, string>, payload?: any): Promise<any>;
@@ -450,6 +526,68 @@ declare class GenerateBasicAuthToken {
     getState(): Promise<any>;
 }
 
+interface ShippingCarrierMethodAdditionalData {
+    key: string;
+    value: any;
+}
+interface ShippingCarrierMethodData {
+    carrier_code: string;
+    method: string;
+    method_title: string;
+    price: number;
+    cost: number;
+    additional_data: ShippingCarrierMethodAdditionalData[];
+}
+
+interface ShippingCarrierData {
+    code: string;
+    title?: string;
+    stores?: string[];
+    countries?: string[];
+    sort_order?: number;
+    active?: boolean;
+    tracking_available?: boolean;
+    shipping_labels_available?: boolean;
+}
+
+declare class ShippingCarrierMethod {
+    private methodData;
+    constructor(carrierCode: string, method: string);
+    setMethodTitle(methodTitle: string): this;
+    setPrice(price: number): this;
+    setCost(cost: number): this;
+    addAdditionalData(key: string, value: any): this;
+    getData(): ShippingCarrierMethodData;
+}
+
+declare class ShippingCarrier {
+    private carrierData;
+    private addedMethods;
+    private removedMethods;
+    constructor(code: string, callback?: (builder: ShippingCarrier) => void);
+    private validateCarrierCode;
+    private validateMethodCode;
+    setTitle(title: string): this;
+    setStores(stores: string[]): this;
+    setCountries(countries: string[]): this;
+    setSortOrder(sortOrder: number): this;
+    setActive(active: boolean): this;
+    setTrackingAvailable(trackingAvailable: boolean): this;
+    setShippingLabelsAvailable(shippingLabelsAvailable: boolean): this;
+    setData(carrierData: ShippingCarrierData): this;
+    addMethod(method: string, callback?: (builder: ShippingCarrierMethod) => void): this;
+    removeMethod(method: string): this;
+    getData(): ShippingCarrierData;
+    getAddedMethods(): ShippingCarrierMethodData[];
+    getRemovedMethods(): string[];
+}
+
+declare class ShippingCarrierResponse {
+    private carrier;
+    constructor(carrier: ShippingCarrier);
+    generate(): WebhookActionResponseType[];
+}
+
 interface AdobeIMSConfig {
     client_id: string;
     client_secrets: string[];
@@ -683,4 +821,4 @@ declare class AdminUiSdk {
     getRegistration(): AdminUiSdkRegistration;
 }
 
-export { AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, BasicAuthConnection, BearerToken, type BearerTokenInfo, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, Openwhisk, OpenwhiskAction, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, type SuccessResponse, type TokenResult, Validator };
+export { AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, BasicAuthConnection, BearerToken, type BearerTokenInfo, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileMetadata, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, Openwhisk, OpenwhiskAction, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, ShippingCarrier, type ShippingCarrierData, ShippingCarrierMethod, type ShippingCarrierMethodAdditionalData, type ShippingCarrierMethodData, ShippingCarrierResponse, SignatureVerification, type SuccessResponse, type TokenResult, Validator, WebhookAction, type WebhookActionAddResponse, type WebhookActionExceptionResponse, WebhookActionOperation, type WebhookActionRemoveResponse, type WebhookActionReplaceResponse, WebhookActionResponse, type WebhookActionResponseType, type WebhookActionSuccessResponse };