@adobe-commerce/aio-toolkit 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,80 @@ 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.1] - 2025-09-22
+
+### 🚀 Enhanced Developer Experience & API Improvements
+
+This patch release focuses on improving developer experience, enhancing API consistency, and streamlining documentation. All changes maintain backward compatibility while introducing new features and improvements.
+
+#### 🔧 API Enhancements
+
+- **RestClient** `[Enhanced]` - Added granular HTTP request control
+  - `makeRequest()` method for raw HTTP requests returning Response objects
+  - `parseResponse()` method for flexible response parsing
+  - `parsed` flag on CRUD methods (get, post, put, delete) to control response parsing
+  - Deprecated `apiCall()` method (maintains backward compatibility)
+  - Enhanced flexibility for handling different response formats
+
+- **HttpMethod Enum** `[Updated]` - Standardized HTTP method values
+  - Updated enum values from lowercase to uppercase (GET, POST, PUT, DELETE, etc.)
+  - Enhanced compliance with HTTP standards
+  - Automatic conversion of incoming method names for backward compatibility
+  - Updated all related tests and validation logic
+
+- **BearerToken** `[Enhanced]` - Improved token extraction and portability
+  - Enhanced `extract()` method to prioritize standard HTTP headers
+  - Fallback support for OpenWhisk-specific `__ow_headers` format
+  - Improved portability across different runtime environments
+  - Enhanced documentation with comprehensive usage examples
+  - Better header parsing for standard HTTP authorization patterns
+
+#### 📚 Documentation Improvements
+
+- **Installation Guide** `[Updated]` - Simplified installation process
+  - Updated root README.md with correct npm installation steps
+  - Removed complex GitHub Packages setup instructions
+  - Streamlined onboarding for new developers
+
+- **FileRepository Documentation** `[Fixed]` - Corrected method signatures
+  - Fixed inaccurate `save()` method documentation showing two parameters
+  - Updated to correct single-parameter `save(payload)` usage
+  - Added comprehensive examples with custom repository classes
+  - Included realistic CRUD operation patterns with proper parameter validation
+  - Updated require paths to use `@lib/EntityRepository` alias
+
+- **Documentation Consolidation** `[Improved]` - Single source of truth
+  - Moved comprehensive package documentation to root README.md
+  - Removed duplicate `docs/` directory structure
+  - Updated package.json scripts to remove docs references
+  - Fixed broken links in CHANGELOG.md
+  - Simplified maintenance with unified documentation approach
+
+#### 🛠️ Package & Repository Enhancements  
+
+- **Package Metadata** `[Cleaned]` - Streamlined package configuration
+  - Removed redundant repository URLs from package.json
+  - Cleaned up external links and badges
+  - Simplified License section to reference local LICENSE file
+  - Removed unnecessary "Support" section
+
+- **Pull Request Template** `[Revised]` - Enhanced contributor workflow
+  - Streamlined PR template for better contributor experience
+  - Added clear sections for changes, motivation, testing, and impact assessment
+  - Improved checklist items for essential quality gates
+  - Reduced complexity while maintaining quality standards
+  - Better guidance for component testing and documentation updates
+
+---
+
+### 🧪 **Quality Assurance**
+
+- **100% Test Coverage Maintained**: All new features and changes fully tested
+- **Zero Breaking Changes**: Complete backward compatibility preserved
+- **Enhanced Error Handling**: Improved error messages and validation
+- **TypeScript Support**: All new APIs fully typed with comprehensive interfaces
+- **Linting & Formatting**: All code meets strict quality standards
+
 ## [1.0.0] - 2025-09-14
 
 ### 🎉 Initial Release
@@ -26,13 +100,13 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
   - Removed duplicate content and improved navigation
 
 #### 🏗️ Commerce Components
-- **[AdobeAuth](./docs/adobe-auth.md)** `[Added]` - Adobe IMS authentication and token management
+- **AdobeAuth** `[Added]` - Adobe IMS authentication and token management
   - Static token retrieval with configurable IMS context
   - Support for custom scopes and client credentials
   - Comprehensive error handling for authentication failures
   - TypeScript interfaces for IMS configuration
 
-- **[AdobeCommerceClient](./docs/adobe-commerce-client.md)** `[Added]` - HTTP client for Adobe Commerce API integration
+- **AdobeCommerceClient** `[Added]` - HTTP client for Adobe Commerce API integration
   - Multiple authentication strategies (Basic Auth, OAuth 1.0a, IMS Bearer Token)
   - Built-in request/response logging and error handling
   - Configurable HTTP client with Got.js integration
@@ -40,38 +114,38 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
   - Connection pattern for extensible authentication
 
 #### 🔧 Framework Components
-- **[EventConsumerAction](./docs/event-consumer-action.md)** `[Added]` - Event-driven processing for Adobe I/O Events
+- **EventConsumerAction** `[Added]` - Event-driven processing for Adobe I/O Events
   - Automatic event validation and processing
   - Configurable retry mechanisms and error handling
   - Support for custom event handlers and middleware
   - Built-in logging and monitoring capabilities
 
-- **[FileRepository](./docs/file-repository.md)** `[Added]` - File-based storage with CRUD operations
+- **FileRepository** `[Added]` - File-based storage with CRUD operations
   - Complete CRUD operations for JSON file management
   - Integration with Adobe I/O Runtime file system
   - Automatic timestamp-based ID generation
   - Error handling with graceful degradation
   - TypeScript interfaces for file records
 
-- **[GraphQlAction](./docs/graphql-action.md)** `[Added]` - GraphQL server implementation
+- **GraphQlAction** `[Added]` - GraphQL server implementation
   - Schema validation and type safety
   - Custom resolver support with context injection
   - Error handling and response formatting
   - Integration with Adobe I/O Runtime
 
-- **[OpenWhisk](./docs/openwhisk.md)** `[Added]` - OpenWhisk client for serverless action invocation
+- **OpenWhisk** `[Added]` - OpenWhisk client for serverless action invocation
   - Direct OpenWhisk action invocation
   - Parameter passing and response handling
   - Error management and timeout handling
   - TypeScript support for action parameters
 
-- **[OpenWhiskAction](./docs/openwhisk-action.md)** `[Added]` - OpenWhisk action wrapper
+- **OpenWhiskAction** `[Added]` - OpenWhisk action wrapper
   - Standardized action structure with logging
   - Request parameter validation
   - Error handling with proper HTTP status codes
   - Extensible base class for custom actions
 
-- **[RuntimeAction](./docs/runtime-action.md)** `[Added]` - HTTP request handling and business logic execution
+- **RuntimeAction** `[Added]` - HTTP request handling and business logic execution
   - Complete HTTP request/response handling
   - Parameter validation and error management
   - Built-in logging and debugging support
@@ -79,20 +153,20 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
   - TypeScript interfaces for all HTTP methods and status codes
 
 #### 🔗 Integration Components
-- **[BearerToken](./docs/bearer-token.md)** `[Added]` - Bearer token extraction utility for OpenWhisk actions
+- **BearerToken** `[Added]` - Bearer token extraction utility for OpenWhisk actions
   - Extract and validate Bearer tokens from OpenWhisk headers
   - JWT token parsing with expiration validation
   - Support for custom token formats
   - Token information extraction with expiry details
 
-- **[InfiniteLoopBreaker](./docs/infinite-loop-breaker.md)** `[Added]` - Detect and prevent infinite loops in event-driven applications
+- **InfiniteLoopBreaker** `[Added]` - Detect and prevent infinite loops in event-driven applications
   - SHA256-based fingerprinting for event deduplication
   - Configurable TTL for stored fingerprints
   - State-based persistence using Adobe I/O State
   - Support for custom key and fingerprint functions
   - Comprehensive error handling and logging
 
-- **[OnboardEvents](./docs/onboard-events.md)** `[Added]` - Complete onboarding orchestration for Adobe I/O Events
+- **OnboardEvents** `[Added]` - Complete onboarding orchestration for Adobe I/O Events
   - **Comprehensive Event Onboarding**: End-to-end orchestration of providers, event metadata, and registrations
   - **Provider Management**: Create and manage Adobe I/O Events providers with commerce-specific metadata
   - **Event Metadata Creation**: Automated event metadata creation with sample templates
@@ -102,7 +176,7 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
   - **Input Validation**: Comprehensive input parsing and validation
   - **TypeScript Support**: Full type definitions for all interfaces and responses
 
-- **[RestClient](./docs/rest-client.md)** `[Added]` - HTTP client for external API integration
+- **RestClient** `[Added]` - HTTP client for external API integration
   - Support for all HTTP methods (GET, POST, PUT, DELETE)
   - Configurable headers and request/response handling
   - Error handling with status code management
@@ -110,21 +184,21 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
   - TypeScript interfaces for headers and responses
 
 #### 📡 I/O Events Components
-- **[EventMetadataManager](./docs/event-metadata.md)** `[Added]` - Manage event metadata for Adobe I/O Events providers
+- **EventMetadataManager** `[Added]` - Manage event metadata for Adobe I/O Events providers
   - Complete CRUD operations for event metadata
   - Sample event template management
   - URL encoding support for event codes
   - Comprehensive error handling and validation
   - TypeScript interfaces for all operations
 
-- **[ProviderManager](./docs/provider.md)** `[Added]` - Manage event providers for Adobe I/O Events
+- **ProviderManager** `[Added]` - Manage event providers for Adobe I/O Events
   - Provider creation, retrieval, updating, and deletion
   - Support for provider metadata and documentation URLs
   - Query parameter support for filtering
   - Commerce-specific provider enhancements
   - Complete HAL+JSON response handling
 
-- **[RegistrationManager](./docs/registration.md)** `[Added]` - Manage event registrations and subscriptions
+- **RegistrationManager** `[Added]` - Manage event registrations and subscriptions
   - Registration lifecycle management
   - Support for webhook, journal, and EventBridge delivery types
   - Event filtering and subscription management
@@ -153,7 +227,7 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
 ## 📦 **Package Information**
 
 - **Package Name**: `@adobe-commerce/aio-toolkit`
-- **Version**: 1.0.0
+- **Version**: 1.0.1
 - **Node.js Support**: >=18.0.0
 - **TypeScript Support**: >=4.9.0
 - **License**: Proprietary (Adobe Commerce)

package/README.md

@@ -1,8 +1,5 @@
 # @adobe-commerce/aio-toolkit
 
-[![npm version](https://badge.fury.io/js/@adobe-commerce%2Faio-toolkit.svg)](https://www.npmjs.com/package/@adobe-commerce/aio-toolkit)
-[![License](https://img.shields.io/badge/license-SEE%20LICENSE%20IN%20LICENSE-blue.svg)](LICENSE)
-
 ## 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.
@@ -182,99 +179,128 @@ exports.main = helloWorldAction;
 #### `FileRepository`
 File-based storage with CRUD operations for Adobe I/O Runtime applications.
 
-```typescript
-const { FileRepository } = require('@adobe-commerce/aio-toolkit');
+**Key Methods:**
+- `save(payload)`: Saves data as a single object parameter. Include `id` in the payload for explicit ID, or omit it for auto-generated timestamp ID.
+- `load(id)`: Loads data by ID
+- `list()`: Lists all stored records
+- `delete(ids)`: Deletes records by ID array
 
-// Initialize file repository
-const orderRepository = new FileRepository('orders');
-const customerRepository = new FileRepository('customers');
+**Best Practice:** Create custom repository classes that extend FileRepository for specific entities.
 
-// Save order data
-const saveOrder = async (orderData) => {
-  const orderId = orderData.orderId;
-  
-  const success = await orderRepository.save(orderId, {
-    ...orderData,
-    createdAt: new Date().toISOString(),
-    status: 'pending'
-  });
-  
-  if (success) {
-    console.log(`Order ${orderId} saved successfully`);
-  } else {
-    throw new Error(`Failed to save order ${orderId}`);
-  }
-};
+##### **1. Define Entity Repository**
+Create a custom repository class extending FileRepository:
 
-// Load order data
-const getOrder = async (orderId) => {
-  const orderData = await orderRepository.load(orderId);
-  
-  if (Object.keys(orderData).length === 0) {
-    throw new Error(`Order ${orderId} not found`);
-  }
-  
-  return orderData;
-};
+```javascript
+const { FileRepository } = require("@adobe-commerce/aio-toolkit");
 
-// List all orders
-const getAllOrders = async () => {
-  const orderFiles = await orderRepository.list();
-  const orders = [];
-  
-  for (const fileName of orderFiles) {
-    const orderId = fileName.replace('.json', '');
-    const orderData = await orderRepository.load(orderId);
-    orders.push({ id: orderId, ...orderData });
-  }
-  
-  return orders;
-};
+class EntityRepository extends FileRepository {
+    /**
+     * @constructor
+     */
+    constructor() {
+        super("/toolkit-demo/entity");
+    }
+}
 
-// Use in a runtime action
-const orderManagerAction = RuntimeAction.execute(
-  'order-manager',
-  ['action', 'orderId'],
-  [],
-  async (params, ctx) => {
-    const { action, orderId } = params;
-    const { logger } = ctx;
-    
-    logger.info(`Order management action: ${action} for ${orderId}`);
-    
-    switch (action) {
-      case 'get':
-        const order = await getOrder(orderId);
-        return RuntimeActionResponse.success({ order });
-        
-      case 'save':
-        await saveOrder(params.orderData);
-        return RuntimeActionResponse.success({ 
-          message: `Order ${orderId} saved` 
-        });
-        
-      case 'list':
-        const orders = await getAllOrders();
-        return RuntimeActionResponse.success({ orders });
-        
-      case 'delete':
-        const deletedOrders = await orderRepository.delete([orderId]);
-        return RuntimeActionResponse.success({ 
-          deleted: deletedOrders.length > 0 
-        });
-        
-      default:
-        return RuntimeActionResponse.error(
-          HttpStatus.BAD_REQUEST,
-          `Unknown action: ${action}`
-        );
+module.exports = EntityRepository;
+```
+
+##### **2. List Action**
+Retrieve all entities from the repository:
+
+```javascript
+const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
+const EntityRepository = require("@lib/EntityRepository");
+
+exports.main = RuntimeAction.execute(
+    "entity-list",
+    [HttpMethod.POST],
+    [],
+    ['Authorization'],
+    async (params) => {
+        const entityRepository = new EntityRepository();
+        return RuntimeActionResponse.success(await entityRepository.list());
+    }
+);
+```
+
+##### **3. Load Action**
+Load a specific entity by ID:
+
+```javascript
+const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
+const EntityRepository = require("@lib/EntityRepository");
+
+exports.main = RuntimeAction.execute(
+    "entity-load",
+    [HttpMethod.POST],
+    ['id'],
+    ['Authorization'],
+    async (params) => {
+        const entityRepository = new EntityRepository();
+        return RuntimeActionResponse.success(await entityRepository.load(params.id));
     }
-  }
 );
+```
 
-exports.main = orderManagerAction;
+##### **4. Save Action**
+Save entity data with proper parameter handling:
+
+```javascript
+const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
+const EntityRepository = require("@lib/EntityRepository");
+
+const requiredParams = [
+    "name",
+    "status"
+];
+
+exports.main = RuntimeAction.execute(
+    "entity-save",
+    [HttpMethod.POST],
+    requiredParams,
+    ['Authorization'],
+    async (params) => {
+        const entityRepository = new EntityRepository();
+
+        let payload = {};
+        for (const fieldName in requiredParams) {
+            payload[requiredParams[fieldName]] = params[requiredParams[fieldName]];
+        }
+        if (Object.prototype.hasOwnProperty.call(params, 'id')) {
+            payload['id'] = params['id'];
+        }
+
+        return RuntimeActionResponse.success((await entityRepository.save(payload)).toString());
+    }
+);
+```
+
+##### **5. Delete Action**
+Delete entities by providing an array of IDs:
+
+```javascript
+const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
+const EntityRepository = require("@lib/EntityRepository");
+
+exports.main = RuntimeAction.execute(
+    "entity-delete",
+    [HttpMethod.POST],
+    ['ids'],
+    ['Authorization'],
+    async (params) => {
+        const entityRepository = new EntityRepository();
+        return RuntimeActionResponse.success(await entityRepository.delete(params.ids));
+    }
+);
 ```
 
+This approach provides:
+- **Separation of concerns**: Each CRUD operation has its own action file
+- **Reusable repository**: Custom repository can be shared across actions
+- **Proper validation**: Required parameters and headers are enforced
+- **Consistent responses**: All actions use RuntimeActionResponse for standardized output
+
 ### 🏪 Commerce Components  
 
 **Adobe Commerce API integration and authentication**
@@ -339,18 +365,46 @@ const response = await client.get('https://api.example.com/data', {
 ```
 
 #### `BearerToken`
-Bearer token extraction and JWT analysis utility.
+Bearer token extraction and JWT analysis utility. Supports both standard HTTP headers and OpenWhisk format for maximum portability.
 
+**Extract from Standard HTTP Headers**
 ```typescript
 const { BearerToken } = require('@adobe-commerce/aio-toolkit');
 
-const tokenInfo = BearerToken.extract(params);
-if (tokenInfo?.token) {
-  console.log('Token expires at:', tokenInfo.expiresAt);
-  console.log('Is expired:', tokenInfo.isExpired);
+const headers = { authorization: 'Bearer abc123token' };
+const tokenInfo = BearerToken.extract(headers);
+console.log(tokenInfo);
+// Output: {
+//   token: 'abc123token',
+//   tokenLength: 11,
+//   isValid: true,
+//   expiry: '2024-01-02T12:00:00.000Z',
+//   timeUntilExpiry: 86400000
+// }
+```
+
+**Extract from OpenWhisk Params (Backward Compatibility)**
+```typescript
+const params = { __ow_headers: { authorization: 'Bearer abc123token' } };
+const owTokenInfo = BearerToken.extract(params);
+console.log(owTokenInfo); // Same output format as above
+```
+
+**Direct Token Analysis**
+```typescript
+const directInfo = BearerToken.info('jwt-token-string');
+if (directInfo.isValid) {
+  console.log(`Token expires at: ${directInfo.expiry}`);
+  console.log(`Time until expiry: ${directInfo.timeUntilExpiry}ms`);
+} else {
+  console.log('Token is invalid or expired');
 }
 ```
 
+**Methods:**
+- `extract(headersOrParams)` - Extracts Bearer token from headers or OpenWhisk params
+- `info(token)` - Analyzes token string and returns validation/expiry details
+
 #### `InfiniteLoopBreaker`
 Detect and prevent infinite loops in event-driven applications.
 
@@ -650,9 +704,4 @@ IO_WORKSPACE_ID=workspace-id
 
 ## License
 
-See the [LICENSE](https://github.com/adobe-commerce/aio-toolkit/blob/main/LICENSE) file for license rights and limitations.
-
-## Support
-
-- **Documentation**: Full API documentation available in TypeScript definitions
-- **Package**: [npm package page](https://www.npmjs.com/package/@adobe-commerce/aio-toolkit)
+See the LICENSE file (in package) for license rights and limitations.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import openwhisk, { Dict, Activation } from 'openwhisk';
+import { Response } from 'node-fetch';
 import { Logger } from '@adobe/aio-sdk';
 import { Got, RequestError } from 'got';
 
@@ -11,13 +12,13 @@ declare enum HttpStatus {
     INTERNAL_ERROR = 500
 }
 declare enum HttpMethod {
-    GET = "get",
-    POST = "post",
-    PUT = "put",
-    DELETE = "delete",
-    PATCH = "patch",
-    HEAD = "head",
-    OPTIONS = "options"
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    DELETE = "DELETE",
+    PATCH = "PATCH",
+    HEAD = "HEAD",
+    OPTIONS = "OPTIONS"
 }
 
 interface SuccessResponse {
@@ -146,7 +147,7 @@ interface BearerTokenInfo {
 }
 
 declare class BearerToken {
-    static extract(params: {
+    static extract(headersOrParams: {
         [key: string]: any;
     }): BearerTokenInfo;
     static info(token: string | null): BearerTokenInfo;
@@ -159,10 +160,12 @@ interface Headers {
 }
 
 declare class RestClient {
-    get(endpoint: string, headers?: Headers): Promise<any>;
-    post(endpoint: string, headers?: Headers, payload?: any): Promise<any>;
-    put(endpoint: string, headers?: Headers, payload?: any): Promise<any>;
-    delete(endpoint: string, headers?: Headers): Promise<any>;
+    makeRequest(endpoint: string, method?: string, headers?: Headers, payload?: any): Promise<Response>;
+    parseResponse(response: Response): Promise<any>;
+    get(endpoint: string, headers?: Headers, parsed?: boolean): Promise<Response | any>;
+    post(endpoint: string, headers?: Headers, payload?: any, parsed?: boolean): Promise<Response | any>;
+    put(endpoint: string, headers?: Headers, payload?: any, parsed?: boolean): Promise<Response | any>;
+    delete(endpoint: string, headers?: Headers, parsed?: boolean): Promise<Response | any>;
     apiCall(endpoint: string, method?: string, headers?: Headers, payload?: any): Promise<any>;
 }
 

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import openwhisk, { Dict, Activation } from 'openwhisk';
+import { Response } from 'node-fetch';
 import { Logger } from '@adobe/aio-sdk';
 import { Got, RequestError } from 'got';
 
@@ -11,13 +12,13 @@ declare enum HttpStatus {
     INTERNAL_ERROR = 500
 }
 declare enum HttpMethod {
-    GET = "get",
-    POST = "post",
-    PUT = "put",
-    DELETE = "delete",
-    PATCH = "patch",
-    HEAD = "head",
-    OPTIONS = "options"
+    GET = "GET",
+    POST = "POST",
+    PUT = "PUT",
+    DELETE = "DELETE",
+    PATCH = "PATCH",
+    HEAD = "HEAD",
+    OPTIONS = "OPTIONS"
 }
 
 interface SuccessResponse {
@@ -146,7 +147,7 @@ interface BearerTokenInfo {
 }
 
 declare class BearerToken {
-    static extract(params: {
+    static extract(headersOrParams: {
         [key: string]: any;
     }): BearerTokenInfo;
     static info(token: string | null): BearerTokenInfo;
@@ -159,10 +160,12 @@ interface Headers {
 }
 
 declare class RestClient {
-    get(endpoint: string, headers?: Headers): Promise<any>;
-    post(endpoint: string, headers?: Headers, payload?: any): Promise<any>;
-    put(endpoint: string, headers?: Headers, payload?: any): Promise<any>;
-    delete(endpoint: string, headers?: Headers): Promise<any>;
+    makeRequest(endpoint: string, method?: string, headers?: Headers, payload?: any): Promise<Response>;
+    parseResponse(response: Response): Promise<any>;
+    get(endpoint: string, headers?: Headers, parsed?: boolean): Promise<Response | any>;
+    post(endpoint: string, headers?: Headers, payload?: any, parsed?: boolean): Promise<Response | any>;
+    put(endpoint: string, headers?: Headers, payload?: any, parsed?: boolean): Promise<Response | any>;
+    delete(endpoint: string, headers?: Headers, parsed?: boolean): Promise<Response | any>;
     apiCall(endpoint: string, method?: string, headers?: Headers, payload?: any): Promise<any>;
 }