@adobe-commerce/aio-toolkit 1.0.1 → 1.0.2

package/CHANGELOG.md

@@ -5,6 +5,50 @@ 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.2] - 2025-09-30
+
+### 🛠️ Framework Component Enhancements & Critical Bug Fixes
+
+This minor release introduces significant enhancements to core framework components, resolving critical issues and adding comprehensive new functionality. Both changes maintain full backward compatibility while substantially improving developer experience and API integration capabilities.
+
+#### 🔧 Framework Components
+
+- **FileRepository** `[Enhanced]` - Optional ID parameter support and standardized file management
+  - Optional ID parameter in save method: `save(payload, id?)` signature
+  - ID parameter takes precedence over payload.id property  
+  - Automatic ID sanitization (alphanumeric + underscore characters only)
+  - Fallback to timestamp-based ID generation for invalid inputs
+  - Enhanced return value: method now returns sanitized filename string instead of boolean
+  - Standardized date formatting with ISO 8601 format for all timestamps
+  - Property naming consistency: `created_at` → `createdAt`, `updated_at` → `updatedAt`
+  - String-only ID handling across all methods with comprehensive error handling
+  - Enhanced type safety with null return values on failures
+
+#### 🔗 Integration Components
+
+- **RestClient** `[Enhanced]` - Comprehensive payload type support resolving critical compatibility issues
+  - URLSearchParams support for form-encoded requests (resolves Issue #40)
+  - FormData support for file uploads and multipart request handling
+  - String payload support for text and XML request transmission  
+  - Binary data support for Buffer, ArrayBuffer, and Uint8Array objects
+  - Smart Content-Type management with user header preservation
+  - Intelligent Content-Type defaults per payload type when not specified
+  - Full backward compatibility maintained for existing JSON usage
+  - Enhanced OAuth2 authentication flow support and form-based API integrations
+
+#### 🐛 Critical Bug Fixes
+
+- **Issue #41 - FileRepository Save Method Enhancement** `[Resolved]`
+  - **Problem**: Missing ID parameter support, incorrect return type, inconsistent date formatting
+  - **Solution**: Complete method signature overhaul with flexible ID handling and proper return types
+  - **Impact**: Enables advanced file management workflows with explicit ID control
+
+- **Issue #40 - RestClient URLSearchParams Failure** `[Resolved]`  
+  - **Problem**: `makeRequest()` failed with 405 Method Not Allowed for form-encoded POST requests
+  - **Root Cause**: Always JSON.stringify() payloads and forced 'application/json' Content-Type
+  - **Solution**: Intelligent payload type detection with appropriate serialization and headers
+  - **Impact**: Enables OAuth2 authentication flows and form-based API integrations
+
 ## [1.0.1] - 2025-09-22
 
 ### 🚀 Enhanced Developer Experience & API Improvements

package/README.md

@@ -180,7 +180,7 @@ exports.main = helloWorldAction;
 File-based storage with CRUD operations for Adobe I/O Runtime applications.
 
 **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.
+- `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
 - `delete(ids)`: Deletes records by ID array
@@ -244,7 +244,7 @@ exports.main = RuntimeAction.execute(
 ```
 
 ##### **4. Save Action**
-Save entity data with proper parameter handling:
+Save entity data with flexible ID handling using the new optional ID parameter:
 
 ```javascript
 const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
@@ -263,15 +263,22 @@ exports.main = RuntimeAction.execute(
     async (params) => {
         const entityRepository = new EntityRepository();
 
+        // Build payload with required fields
         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());
+        // Extract ID parameter for prioritized handling
+        const explicitId = params.id || params.customId || null;
+        
+        // Save with optional ID parameter - it takes precedence over payload.id
+        const savedId = await entityRepository.save(payload, explicitId);
+
+        return RuntimeActionResponse.success({
+            id: savedId,
+            message: 'Entity saved successfully'
+        });
     }
 );
 ```
@@ -297,9 +304,11 @@ exports.main = RuntimeAction.execute(
 
 This approach provides:
 - **Separation of concerns**: Each CRUD operation has its own action file
-- **Reusable repository**: Custom repository can be shared across actions
+- **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
+- **Flexible ID management**: Support for explicit IDs, payload IDs, and auto-generation
+- **Automatic sanitization**: IDs are cleaned to ensure file system compatibility
 
 ### 🏪 Commerce Components  
 
@@ -352,18 +361,65 @@ const newProduct = await client.post('rest/V1/products', {}, productData);
 **External API integration and utility functions**
 
 #### `RestClient`
-HTTP client for external API integration.
+HTTP client for external API integration with support for various payload types.
 
+**Basic Usage**
 ```typescript
 const { RestClient } = require('@adobe-commerce/aio-toolkit');
 
 const client = new RestClient();
+
+// GET request
 const response = await client.get('https://api.example.com/data', {
-  'Authorization': 'Bearer token',
-  'Content-Type': 'application/json'
+  'Authorization': 'Bearer token'
 });
 ```
 
+**JSON Payloads (default)**
+```typescript
+// POST with JSON (automatic Content-Type: application/json)
+const jsonData = { name: 'Product', price: 99.99 };
+const response = await client.post('https://api.example.com/products', {
+  'Authorization': 'Bearer token'
+}, jsonData);
+```
+
+**Form-Encoded Requests**
+```typescript
+// URLSearchParams for form-encoded data (automatic Content-Type: application/x-www-form-urlencoded)
+const formData = new URLSearchParams({
+  grant_type: 'client_credentials',
+  client_id: 'your-client-id',
+  client_secret: 'your-client-secret'
+});
+
+const tokenResponse = await client.post('https://auth.example.com/token', {
+  Accept: 'application/json'
+}, formData);
+```
+
+**File Upload**
+```typescript
+// FormData for file uploads (Content-Type boundary handled automatically)
+const uploadData = new FormData();
+uploadData.append('file', fileBuffer, 'document.pdf');
+uploadData.append('description', 'Important document');
+
+const uploadResponse = await client.post('https://api.example.com/upload', {
+  'Authorization': 'Bearer token'
+}, uploadData);
+```
+
+**Text/XML Payloads**
+```typescript
+// String payloads with custom content type
+const xmlData = '<?xml version="1.0"?><order><id>123</id></order>';
+const xmlResponse = await client.post('https://api.example.com/orders', {
+  'Authorization': 'Bearer token',
+  'Content-Type': 'application/xml'
+}, xmlData);
+```
+
 #### `BearerToken`
 Bearer token extraction and JWT analysis utility. Supports both standard HTTP headers and OpenWhisk format for maximum portability.
 

package/dist/index.d.mts

@@ -121,9 +121,9 @@ declare class OpenwhiskAction {
 }
 
 interface FileRecord {
-    id: string | number;
-    created_at: string;
-    updated_at: string;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
     [key: string]: any;
 }
 
@@ -133,8 +133,9 @@ declare class FileRepository {
     constructor(filepath: string);
     list(): Promise<FileRecord[]>;
     load(id?: string): Promise<FileRecord>;
-    save(payload?: Partial<FileRecord>): Promise<boolean>;
-    delete(ids?: (string | number)[]): Promise<FileRecord[]>;
+    save(payload?: Partial<FileRecord>, id?: string | null): Promise<string | null>;
+    delete(ids?: string[]): Promise<FileRecord[]>;
+    private sanitizeFileId;
     private getFiles;
 }
 

package/dist/index.d.ts

@@ -121,9 +121,9 @@ declare class OpenwhiskAction {
 }
 
 interface FileRecord {
-    id: string | number;
-    created_at: string;
-    updated_at: string;
+    id: string;
+    createdAt: string;
+    updatedAt: string;
     [key: string]: any;
 }
 
@@ -133,8 +133,9 @@ declare class FileRepository {
     constructor(filepath: string);
     list(): Promise<FileRecord[]>;
     load(id?: string): Promise<FileRecord>;
-    save(payload?: Partial<FileRecord>): Promise<boolean>;
-    delete(ids?: (string | number)[]): Promise<FileRecord[]>;
+    save(payload?: Partial<FileRecord>, id?: string | null): Promise<string | null>;
+    delete(ids?: string[]): Promise<FileRecord[]>;
+    private sanitizeFileId;
     private getFiles;
 }
 

package/dist/index.js

@@ -484,39 +484,44 @@ var _FileRepository = class _FileRepository {
   /**
    * Saves a file record to the repository
    * @param payload - The data to save
-   * @returns Promise<boolean> True if save was successful, false otherwise
+   * @param id - Optional ID for the file (sanitized to alphanumeric + underscore, takes precedence over payload.id)
+   * @returns Promise<string | null> The filename on success, null on failure
    */
-  async save(payload = {}) {
+  async save(payload = {}, id) {
     try {
       const filesLib = await this.getFiles();
-      let requestFileId = (/* @__PURE__ */ new Date()).getTime();
-      if ("id" in payload && payload.id !== void 0) {
-        requestFileId = Number(payload.id);
+      let fileId;
+      if (id) {
+        fileId = this.sanitizeFileId(id);
+      } else if ("id" in payload && payload.id !== void 0) {
+        fileId = String(payload.id);
+      } else {
+        fileId = String((/* @__PURE__ */ new Date()).getTime());
       }
-      const filepath = `${this.filepath}/${requestFileId}.json`;
+      const filepath = `${this.filepath}/${fileId}.json`;
       const existingFile = await filesLib.list(filepath);
       if (existingFile.length) {
         const buffer = await filesLib.read(filepath);
         const existingData = JSON.parse(buffer.toString());
         payload = {
           ...payload,
-          updated_at: (/* @__PURE__ */ new Date()).toDateString()
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         };
         payload = { ...existingData, ...payload };
         await filesLib.delete(filepath);
       } else {
         payload = {
           ...payload,
-          id: requestFileId,
-          created_at: (/* @__PURE__ */ new Date()).toDateString(),
-          updated_at: (/* @__PURE__ */ new Date()).toDateString()
+          id: fileId,
+          createdAt: (/* @__PURE__ */ new Date()).toISOString(),
+          updatedAt: (/* @__PURE__ */ new Date()).toISOString()
         };
       }
       await filesLib.write(filepath, JSON.stringify(payload));
-      return true;
+      return fileId;
     } catch (error) {
       console.error("Error saving file:", error);
-      return false;
+      return null;
     }
   }
   /**
@@ -531,6 +536,21 @@ var _FileRepository = class _FileRepository {
     }
     return await this.list();
   }
+  /**
+   * Sanitizes the file ID to contain only alphanumeric characters and underscores
+   * @param id - The ID to sanitize
+   * @returns Sanitized ID with invalid characters replaced by underscores
+   */
+  sanitizeFileId(id) {
+    if (!id || typeof id !== "string") {
+      return String((/* @__PURE__ */ new Date()).getTime());
+    }
+    const sanitized = id.replace(/[^a-zA-Z0-9_]/g, "_");
+    if (!sanitized || /^_+$/.test(sanitized)) {
+      return String((/* @__PURE__ */ new Date()).getTime());
+    }
+    return sanitized;
+  }
   /**
    * Initializes and returns the Files library instance
    * @returns Promise<any> Initialized Files library instance
@@ -708,13 +728,32 @@ var _RestClient = class _RestClient {
       headers
     };
     if (payload !== null) {
+      let body;
+      let contentType;
+      if (payload instanceof URLSearchParams) {
+        body = payload.toString();
+        contentType = headers["Content-Type"] || "application/x-www-form-urlencoded";
+      } else if (typeof FormData !== "undefined" && payload instanceof FormData) {
+        body = payload;
+        contentType = headers["Content-Type"];
+      } else if (typeof payload === "string") {
+        body = payload;
+        contentType = headers["Content-Type"] || "text/plain";
+      } else if (payload instanceof Buffer || payload instanceof ArrayBuffer || typeof Uint8Array !== "undefined" && payload instanceof Uint8Array) {
+        body = payload;
+        contentType = headers["Content-Type"] || "application/octet-stream";
+      } else {
+        body = JSON.stringify(payload);
+        contentType = headers["Content-Type"] || "application/json";
+      }
+      const requestHeaders = { ...headers };
+      if (contentType) {
+        requestHeaders["Content-Type"] = contentType;
+      }
       options = {
         ...options,
-        body: JSON.stringify(payload),
-        headers: {
-          ...headers,
-          "Content-Type": "application/json"
-        }
+        body,
+        headers: requestHeaders
       };
     }
     return await (0, import_node_fetch.default)(endpoint, options);