@adobe-commerce/aio-toolkit 1.0.0 โ†’ 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -5,6 +5,124 @@ All notable changes to this project will be documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.0.2] - 2025-09-30
9
+
10
+ ### ๐Ÿ› ๏ธ Framework Component Enhancements & Critical Bug Fixes
11
+
12
+ 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.
13
+
14
+ #### ๐Ÿ”ง Framework Components
15
+
16
+ - **FileRepository** `[Enhanced]` - Optional ID parameter support and standardized file management
17
+ - Optional ID parameter in save method: `save(payload, id?)` signature
18
+ - ID parameter takes precedence over payload.id property
19
+ - Automatic ID sanitization (alphanumeric + underscore characters only)
20
+ - Fallback to timestamp-based ID generation for invalid inputs
21
+ - Enhanced return value: method now returns sanitized filename string instead of boolean
22
+ - Standardized date formatting with ISO 8601 format for all timestamps
23
+ - Property naming consistency: `created_at` โ†’ `createdAt`, `updated_at` โ†’ `updatedAt`
24
+ - String-only ID handling across all methods with comprehensive error handling
25
+ - Enhanced type safety with null return values on failures
26
+
27
+ #### ๐Ÿ”— Integration Components
28
+
29
+ - **RestClient** `[Enhanced]` - Comprehensive payload type support resolving critical compatibility issues
30
+ - URLSearchParams support for form-encoded requests (resolves Issue #40)
31
+ - FormData support for file uploads and multipart request handling
32
+ - String payload support for text and XML request transmission
33
+ - Binary data support for Buffer, ArrayBuffer, and Uint8Array objects
34
+ - Smart Content-Type management with user header preservation
35
+ - Intelligent Content-Type defaults per payload type when not specified
36
+ - Full backward compatibility maintained for existing JSON usage
37
+ - Enhanced OAuth2 authentication flow support and form-based API integrations
38
+
39
+ #### ๐Ÿ› Critical Bug Fixes
40
+
41
+ - **Issue #41 - FileRepository Save Method Enhancement** `[Resolved]`
42
+ - **Problem**: Missing ID parameter support, incorrect return type, inconsistent date formatting
43
+ - **Solution**: Complete method signature overhaul with flexible ID handling and proper return types
44
+ - **Impact**: Enables advanced file management workflows with explicit ID control
45
+
46
+ - **Issue #40 - RestClient URLSearchParams Failure** `[Resolved]`
47
+ - **Problem**: `makeRequest()` failed with 405 Method Not Allowed for form-encoded POST requests
48
+ - **Root Cause**: Always JSON.stringify() payloads and forced 'application/json' Content-Type
49
+ - **Solution**: Intelligent payload type detection with appropriate serialization and headers
50
+ - **Impact**: Enables OAuth2 authentication flows and form-based API integrations
51
+
52
+ ## [1.0.1] - 2025-09-22
53
+
54
+ ### ๐Ÿš€ Enhanced Developer Experience & API Improvements
55
+
56
+ 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.
57
+
58
+ #### ๐Ÿ”ง API Enhancements
59
+
60
+ - **RestClient** `[Enhanced]` - Added granular HTTP request control
61
+ - `makeRequest()` method for raw HTTP requests returning Response objects
62
+ - `parseResponse()` method for flexible response parsing
63
+ - `parsed` flag on CRUD methods (get, post, put, delete) to control response parsing
64
+ - Deprecated `apiCall()` method (maintains backward compatibility)
65
+ - Enhanced flexibility for handling different response formats
66
+
67
+ - **HttpMethod Enum** `[Updated]` - Standardized HTTP method values
68
+ - Updated enum values from lowercase to uppercase (GET, POST, PUT, DELETE, etc.)
69
+ - Enhanced compliance with HTTP standards
70
+ - Automatic conversion of incoming method names for backward compatibility
71
+ - Updated all related tests and validation logic
72
+
73
+ - **BearerToken** `[Enhanced]` - Improved token extraction and portability
74
+ - Enhanced `extract()` method to prioritize standard HTTP headers
75
+ - Fallback support for OpenWhisk-specific `__ow_headers` format
76
+ - Improved portability across different runtime environments
77
+ - Enhanced documentation with comprehensive usage examples
78
+ - Better header parsing for standard HTTP authorization patterns
79
+
80
+ #### ๐Ÿ“š Documentation Improvements
81
+
82
+ - **Installation Guide** `[Updated]` - Simplified installation process
83
+ - Updated root README.md with correct npm installation steps
84
+ - Removed complex GitHub Packages setup instructions
85
+ - Streamlined onboarding for new developers
86
+
87
+ - **FileRepository Documentation** `[Fixed]` - Corrected method signatures
88
+ - Fixed inaccurate `save()` method documentation showing two parameters
89
+ - Updated to correct single-parameter `save(payload)` usage
90
+ - Added comprehensive examples with custom repository classes
91
+ - Included realistic CRUD operation patterns with proper parameter validation
92
+ - Updated require paths to use `@lib/EntityRepository` alias
93
+
94
+ - **Documentation Consolidation** `[Improved]` - Single source of truth
95
+ - Moved comprehensive package documentation to root README.md
96
+ - Removed duplicate `docs/` directory structure
97
+ - Updated package.json scripts to remove docs references
98
+ - Fixed broken links in CHANGELOG.md
99
+ - Simplified maintenance with unified documentation approach
100
+
101
+ #### ๐Ÿ› ๏ธ Package & Repository Enhancements
102
+
103
+ - **Package Metadata** `[Cleaned]` - Streamlined package configuration
104
+ - Removed redundant repository URLs from package.json
105
+ - Cleaned up external links and badges
106
+ - Simplified License section to reference local LICENSE file
107
+ - Removed unnecessary "Support" section
108
+
109
+ - **Pull Request Template** `[Revised]` - Enhanced contributor workflow
110
+ - Streamlined PR template for better contributor experience
111
+ - Added clear sections for changes, motivation, testing, and impact assessment
112
+ - Improved checklist items for essential quality gates
113
+ - Reduced complexity while maintaining quality standards
114
+ - Better guidance for component testing and documentation updates
115
+
116
+ ---
117
+
118
+ ### ๐Ÿงช **Quality Assurance**
119
+
120
+ - **100% Test Coverage Maintained**: All new features and changes fully tested
121
+ - **Zero Breaking Changes**: Complete backward compatibility preserved
122
+ - **Enhanced Error Handling**: Improved error messages and validation
123
+ - **TypeScript Support**: All new APIs fully typed with comprehensive interfaces
124
+ - **Linting & Formatting**: All code meets strict quality standards
125
+
8
126
  ## [1.0.0] - 2025-09-14
9
127
 
10
128
  ### ๐ŸŽ‰ Initial Release
@@ -26,13 +144,13 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
26
144
  - Removed duplicate content and improved navigation
27
145
 
28
146
  #### ๐Ÿ—๏ธ Commerce Components
29
- - **[AdobeAuth](./docs/adobe-auth.md)** `[Added]` - Adobe IMS authentication and token management
147
+ - **AdobeAuth** `[Added]` - Adobe IMS authentication and token management
30
148
  - Static token retrieval with configurable IMS context
31
149
  - Support for custom scopes and client credentials
32
150
  - Comprehensive error handling for authentication failures
33
151
  - TypeScript interfaces for IMS configuration
34
152
 
35
- - **[AdobeCommerceClient](./docs/adobe-commerce-client.md)** `[Added]` - HTTP client for Adobe Commerce API integration
153
+ - **AdobeCommerceClient** `[Added]` - HTTP client for Adobe Commerce API integration
36
154
  - Multiple authentication strategies (Basic Auth, OAuth 1.0a, IMS Bearer Token)
37
155
  - Built-in request/response logging and error handling
38
156
  - Configurable HTTP client with Got.js integration
@@ -40,38 +158,38 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
40
158
  - Connection pattern for extensible authentication
41
159
 
42
160
  #### ๐Ÿ”ง Framework Components
43
- - **[EventConsumerAction](./docs/event-consumer-action.md)** `[Added]` - Event-driven processing for Adobe I/O Events
161
+ - **EventConsumerAction** `[Added]` - Event-driven processing for Adobe I/O Events
44
162
  - Automatic event validation and processing
45
163
  - Configurable retry mechanisms and error handling
46
164
  - Support for custom event handlers and middleware
47
165
  - Built-in logging and monitoring capabilities
48
166
 
49
- - **[FileRepository](./docs/file-repository.md)** `[Added]` - File-based storage with CRUD operations
167
+ - **FileRepository** `[Added]` - File-based storage with CRUD operations
50
168
  - Complete CRUD operations for JSON file management
51
169
  - Integration with Adobe I/O Runtime file system
52
170
  - Automatic timestamp-based ID generation
53
171
  - Error handling with graceful degradation
54
172
  - TypeScript interfaces for file records
55
173
 
56
- - **[GraphQlAction](./docs/graphql-action.md)** `[Added]` - GraphQL server implementation
174
+ - **GraphQlAction** `[Added]` - GraphQL server implementation
57
175
  - Schema validation and type safety
58
176
  - Custom resolver support with context injection
59
177
  - Error handling and response formatting
60
178
  - Integration with Adobe I/O Runtime
61
179
 
62
- - **[OpenWhisk](./docs/openwhisk.md)** `[Added]` - OpenWhisk client for serverless action invocation
180
+ - **OpenWhisk** `[Added]` - OpenWhisk client for serverless action invocation
63
181
  - Direct OpenWhisk action invocation
64
182
  - Parameter passing and response handling
65
183
  - Error management and timeout handling
66
184
  - TypeScript support for action parameters
67
185
 
68
- - **[OpenWhiskAction](./docs/openwhisk-action.md)** `[Added]` - OpenWhisk action wrapper
186
+ - **OpenWhiskAction** `[Added]` - OpenWhisk action wrapper
69
187
  - Standardized action structure with logging
70
188
  - Request parameter validation
71
189
  - Error handling with proper HTTP status codes
72
190
  - Extensible base class for custom actions
73
191
 
74
- - **[RuntimeAction](./docs/runtime-action.md)** `[Added]` - HTTP request handling and business logic execution
192
+ - **RuntimeAction** `[Added]` - HTTP request handling and business logic execution
75
193
  - Complete HTTP request/response handling
76
194
  - Parameter validation and error management
77
195
  - Built-in logging and debugging support
@@ -79,20 +197,20 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
79
197
  - TypeScript interfaces for all HTTP methods and status codes
80
198
 
81
199
  #### ๐Ÿ”— Integration Components
82
- - **[BearerToken](./docs/bearer-token.md)** `[Added]` - Bearer token extraction utility for OpenWhisk actions
200
+ - **BearerToken** `[Added]` - Bearer token extraction utility for OpenWhisk actions
83
201
  - Extract and validate Bearer tokens from OpenWhisk headers
84
202
  - JWT token parsing with expiration validation
85
203
  - Support for custom token formats
86
204
  - Token information extraction with expiry details
87
205
 
88
- - **[InfiniteLoopBreaker](./docs/infinite-loop-breaker.md)** `[Added]` - Detect and prevent infinite loops in event-driven applications
206
+ - **InfiniteLoopBreaker** `[Added]` - Detect and prevent infinite loops in event-driven applications
89
207
  - SHA256-based fingerprinting for event deduplication
90
208
  - Configurable TTL for stored fingerprints
91
209
  - State-based persistence using Adobe I/O State
92
210
  - Support for custom key and fingerprint functions
93
211
  - Comprehensive error handling and logging
94
212
 
95
- - **[OnboardEvents](./docs/onboard-events.md)** `[Added]` - Complete onboarding orchestration for Adobe I/O Events
213
+ - **OnboardEvents** `[Added]` - Complete onboarding orchestration for Adobe I/O Events
96
214
  - **Comprehensive Event Onboarding**: End-to-end orchestration of providers, event metadata, and registrations
97
215
  - **Provider Management**: Create and manage Adobe I/O Events providers with commerce-specific metadata
98
216
  - **Event Metadata Creation**: Automated event metadata creation with sample templates
@@ -102,7 +220,7 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
102
220
  - **Input Validation**: Comprehensive input parsing and validation
103
221
  - **TypeScript Support**: Full type definitions for all interfaces and responses
104
222
 
105
- - **[RestClient](./docs/rest-client.md)** `[Added]` - HTTP client for external API integration
223
+ - **RestClient** `[Added]` - HTTP client for external API integration
106
224
  - Support for all HTTP methods (GET, POST, PUT, DELETE)
107
225
  - Configurable headers and request/response handling
108
226
  - Error handling with status code management
@@ -110,21 +228,21 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
110
228
  - TypeScript interfaces for headers and responses
111
229
 
112
230
  #### ๐Ÿ“ก I/O Events Components
113
- - **[EventMetadataManager](./docs/event-metadata.md)** `[Added]` - Manage event metadata for Adobe I/O Events providers
231
+ - **EventMetadataManager** `[Added]` - Manage event metadata for Adobe I/O Events providers
114
232
  - Complete CRUD operations for event metadata
115
233
  - Sample event template management
116
234
  - URL encoding support for event codes
117
235
  - Comprehensive error handling and validation
118
236
  - TypeScript interfaces for all operations
119
237
 
120
- - **[ProviderManager](./docs/provider.md)** `[Added]` - Manage event providers for Adobe I/O Events
238
+ - **ProviderManager** `[Added]` - Manage event providers for Adobe I/O Events
121
239
  - Provider creation, retrieval, updating, and deletion
122
240
  - Support for provider metadata and documentation URLs
123
241
  - Query parameter support for filtering
124
242
  - Commerce-specific provider enhancements
125
243
  - Complete HAL+JSON response handling
126
244
 
127
- - **[RegistrationManager](./docs/registration.md)** `[Added]` - Manage event registrations and subscriptions
245
+ - **RegistrationManager** `[Added]` - Manage event registrations and subscriptions
128
246
  - Registration lifecycle management
129
247
  - Support for webhook, journal, and EventBridge delivery types
130
248
  - Event filtering and subscription management
@@ -153,7 +271,7 @@ This is the first stable release of the **@adobe-commerce/aio-toolkit** - a comp
153
271
  ## ๐Ÿ“ฆ **Package Information**
154
272
 
155
273
  - **Package Name**: `@adobe-commerce/aio-toolkit`
156
- - **Version**: 1.0.0
274
+ - **Version**: 1.0.1
157
275
  - **Node.js Support**: >=18.0.0
158
276
  - **TypeScript Support**: >=4.9.0
159
277
  - **License**: Proprietary (Adobe Commerce)
package/README.md CHANGED
@@ -1,8 +1,5 @@
1
1
  # @adobe-commerce/aio-toolkit
2
2
 
3
- [![npm version](https://badge.fury.io/js/@adobe-commerce%2Faio-toolkit.svg)](https://www.npmjs.com/package/@adobe-commerce/aio-toolkit)
4
- [![License](https://img.shields.io/badge/license-SEE%20LICENSE%20IN%20LICENSE-blue.svg)](LICENSE)
5
-
6
3
  ## Overview
7
4
 
8
5
  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,137 @@ exports.main = helloWorldAction;
182
179
  #### `FileRepository`
183
180
  File-based storage with CRUD operations for Adobe I/O Runtime applications.
184
181
 
185
- ```typescript
186
- const { FileRepository } = require('@adobe-commerce/aio-toolkit');
182
+ **Key Methods:**
183
+ - `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.
184
+ - `load(id)`: Loads data by ID
185
+ - `list()`: Lists all stored records
186
+ - `delete(ids)`: Deletes records by ID array
187
187
 
188
- // Initialize file repository
189
- const orderRepository = new FileRepository('orders');
190
- const customerRepository = new FileRepository('customers');
188
+ **Best Practice:** Create custom repository classes that extend FileRepository for specific entities.
191
189
 
192
- // Save order data
193
- const saveOrder = async (orderData) => {
194
- const orderId = orderData.orderId;
195
-
196
- const success = await orderRepository.save(orderId, {
197
- ...orderData,
198
- createdAt: new Date().toISOString(),
199
- status: 'pending'
200
- });
201
-
202
- if (success) {
203
- console.log(`Order ${orderId} saved successfully`);
204
- } else {
205
- throw new Error(`Failed to save order ${orderId}`);
206
- }
207
- };
190
+ ##### **1. Define Entity Repository**
191
+ Create a custom repository class extending FileRepository:
208
192
 
209
- // Load order data
210
- const getOrder = async (orderId) => {
211
- const orderData = await orderRepository.load(orderId);
212
-
213
- if (Object.keys(orderData).length === 0) {
214
- throw new Error(`Order ${orderId} not found`);
215
- }
216
-
217
- return orderData;
218
- };
193
+ ```javascript
194
+ const { FileRepository } = require("@adobe-commerce/aio-toolkit");
219
195
 
220
- // List all orders
221
- const getAllOrders = async () => {
222
- const orderFiles = await orderRepository.list();
223
- const orders = [];
224
-
225
- for (const fileName of orderFiles) {
226
- const orderId = fileName.replace('.json', '');
227
- const orderData = await orderRepository.load(orderId);
228
- orders.push({ id: orderId, ...orderData });
229
- }
230
-
231
- return orders;
232
- };
196
+ class EntityRepository extends FileRepository {
197
+ /**
198
+ * @constructor
199
+ */
200
+ constructor() {
201
+ super("/toolkit-demo/entity");
202
+ }
203
+ }
233
204
 
234
- // Use in a runtime action
235
- const orderManagerAction = RuntimeAction.execute(
236
- 'order-manager',
237
- ['action', 'orderId'],
238
- [],
239
- async (params, ctx) => {
240
- const { action, orderId } = params;
241
- const { logger } = ctx;
242
-
243
- logger.info(`Order management action: ${action} for ${orderId}`);
244
-
245
- switch (action) {
246
- case 'get':
247
- const order = await getOrder(orderId);
248
- return RuntimeActionResponse.success({ order });
249
-
250
- case 'save':
251
- await saveOrder(params.orderData);
252
- return RuntimeActionResponse.success({
253
- message: `Order ${orderId} saved`
254
- });
255
-
256
- case 'list':
257
- const orders = await getAllOrders();
258
- return RuntimeActionResponse.success({ orders });
205
+ module.exports = EntityRepository;
206
+ ```
207
+
208
+ ##### **2. List Action**
209
+ Retrieve all entities from the repository:
210
+
211
+ ```javascript
212
+ const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
213
+ const EntityRepository = require("@lib/EntityRepository");
214
+
215
+ exports.main = RuntimeAction.execute(
216
+ "entity-list",
217
+ [HttpMethod.POST],
218
+ [],
219
+ ['Authorization'],
220
+ async (params) => {
221
+ const entityRepository = new EntityRepository();
222
+ return RuntimeActionResponse.success(await entityRepository.list());
223
+ }
224
+ );
225
+ ```
226
+
227
+ ##### **3. Load Action**
228
+ Load a specific entity by ID:
229
+
230
+ ```javascript
231
+ const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
232
+ const EntityRepository = require("@lib/EntityRepository");
233
+
234
+ exports.main = RuntimeAction.execute(
235
+ "entity-load",
236
+ [HttpMethod.POST],
237
+ ['id'],
238
+ ['Authorization'],
239
+ async (params) => {
240
+ const entityRepository = new EntityRepository();
241
+ return RuntimeActionResponse.success(await entityRepository.load(params.id));
242
+ }
243
+ );
244
+ ```
245
+
246
+ ##### **4. Save Action**
247
+ Save entity data with flexible ID handling using the new optional ID parameter:
248
+
249
+ ```javascript
250
+ const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
251
+ const EntityRepository = require("@lib/EntityRepository");
252
+
253
+ const requiredParams = [
254
+ "name",
255
+ "status"
256
+ ];
257
+
258
+ exports.main = RuntimeAction.execute(
259
+ "entity-save",
260
+ [HttpMethod.POST],
261
+ requiredParams,
262
+ ['Authorization'],
263
+ async (params) => {
264
+ const entityRepository = new EntityRepository();
265
+
266
+ // Build payload with required fields
267
+ let payload = {};
268
+ for (const fieldName in requiredParams) {
269
+ payload[requiredParams[fieldName]] = params[requiredParams[fieldName]];
270
+ }
271
+
272
+ // Extract ID parameter for prioritized handling
273
+ const explicitId = params.id || params.customId || null;
259
274
 
260
- case 'delete':
261
- const deletedOrders = await orderRepository.delete([orderId]);
262
- return RuntimeActionResponse.success({
263
- deleted: deletedOrders.length > 0
275
+ // Save with optional ID parameter - it takes precedence over payload.id
276
+ const savedId = await entityRepository.save(payload, explicitId);
277
+
278
+ return RuntimeActionResponse.success({
279
+ id: savedId,
280
+ message: 'Entity saved successfully'
264
281
  });
265
-
266
- default:
267
- return RuntimeActionResponse.error(
268
- HttpStatus.BAD_REQUEST,
269
- `Unknown action: ${action}`
270
- );
271
282
  }
272
- }
273
283
  );
284
+ ```
274
285
 
275
- exports.main = orderManagerAction;
286
+ ##### **5. Delete Action**
287
+ Delete entities by providing an array of IDs:
288
+
289
+ ```javascript
290
+ const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require("@adobe-commerce/aio-toolkit");
291
+ const EntityRepository = require("@lib/EntityRepository");
292
+
293
+ exports.main = RuntimeAction.execute(
294
+ "entity-delete",
295
+ [HttpMethod.POST],
296
+ ['ids'],
297
+ ['Authorization'],
298
+ async (params) => {
299
+ const entityRepository = new EntityRepository();
300
+ return RuntimeActionResponse.success(await entityRepository.delete(params.ids));
301
+ }
302
+ );
276
303
  ```
277
304
 
305
+ This approach provides:
306
+ - **Separation of concerns**: Each CRUD operation has its own action file
307
+ - **Reusable repository**: Custom repository can be shared across actions
308
+ - **Proper validation**: Required parameters and headers are enforced
309
+ - **Consistent responses**: All actions use RuntimeActionResponse for standardized output
310
+ - **Flexible ID management**: Support for explicit IDs, payload IDs, and auto-generation
311
+ - **Automatic sanitization**: IDs are cleaned to ensure file system compatibility
312
+
278
313
  ### ๐Ÿช Commerce Components
279
314
 
280
315
  **Adobe Commerce API integration and authentication**
@@ -326,31 +361,106 @@ const newProduct = await client.post('rest/V1/products', {}, productData);
326
361
  **External API integration and utility functions**
327
362
 
328
363
  #### `RestClient`
329
- HTTP client for external API integration.
364
+ HTTP client for external API integration with support for various payload types.
330
365
 
366
+ **Basic Usage**
331
367
  ```typescript
332
368
  const { RestClient } = require('@adobe-commerce/aio-toolkit');
333
369
 
334
370
  const client = new RestClient();
371
+
372
+ // GET request
335
373
  const response = await client.get('https://api.example.com/data', {
336
- 'Authorization': 'Bearer token',
337
- 'Content-Type': 'application/json'
374
+ 'Authorization': 'Bearer token'
338
375
  });
339
376
  ```
340
377
 
378
+ **JSON Payloads (default)**
379
+ ```typescript
380
+ // POST with JSON (automatic Content-Type: application/json)
381
+ const jsonData = { name: 'Product', price: 99.99 };
382
+ const response = await client.post('https://api.example.com/products', {
383
+ 'Authorization': 'Bearer token'
384
+ }, jsonData);
385
+ ```
386
+
387
+ **Form-Encoded Requests**
388
+ ```typescript
389
+ // URLSearchParams for form-encoded data (automatic Content-Type: application/x-www-form-urlencoded)
390
+ const formData = new URLSearchParams({
391
+ grant_type: 'client_credentials',
392
+ client_id: 'your-client-id',
393
+ client_secret: 'your-client-secret'
394
+ });
395
+
396
+ const tokenResponse = await client.post('https://auth.example.com/token', {
397
+ Accept: 'application/json'
398
+ }, formData);
399
+ ```
400
+
401
+ **File Upload**
402
+ ```typescript
403
+ // FormData for file uploads (Content-Type boundary handled automatically)
404
+ const uploadData = new FormData();
405
+ uploadData.append('file', fileBuffer, 'document.pdf');
406
+ uploadData.append('description', 'Important document');
407
+
408
+ const uploadResponse = await client.post('https://api.example.com/upload', {
409
+ 'Authorization': 'Bearer token'
410
+ }, uploadData);
411
+ ```
412
+
413
+ **Text/XML Payloads**
414
+ ```typescript
415
+ // String payloads with custom content type
416
+ const xmlData = '<?xml version="1.0"?><order><id>123</id></order>';
417
+ const xmlResponse = await client.post('https://api.example.com/orders', {
418
+ 'Authorization': 'Bearer token',
419
+ 'Content-Type': 'application/xml'
420
+ }, xmlData);
421
+ ```
422
+
341
423
  #### `BearerToken`
342
- Bearer token extraction and JWT analysis utility.
424
+ Bearer token extraction and JWT analysis utility. Supports both standard HTTP headers and OpenWhisk format for maximum portability.
343
425
 
426
+ **Extract from Standard HTTP Headers**
344
427
  ```typescript
345
428
  const { BearerToken } = require('@adobe-commerce/aio-toolkit');
346
429
 
347
- const tokenInfo = BearerToken.extract(params);
348
- if (tokenInfo?.token) {
349
- console.log('Token expires at:', tokenInfo.expiresAt);
350
- console.log('Is expired:', tokenInfo.isExpired);
430
+ const headers = { authorization: 'Bearer abc123token' };
431
+ const tokenInfo = BearerToken.extract(headers);
432
+ console.log(tokenInfo);
433
+ // Output: {
434
+ // token: 'abc123token',
435
+ // tokenLength: 11,
436
+ // isValid: true,
437
+ // expiry: '2024-01-02T12:00:00.000Z',
438
+ // timeUntilExpiry: 86400000
439
+ // }
440
+ ```
441
+
442
+ **Extract from OpenWhisk Params (Backward Compatibility)**
443
+ ```typescript
444
+ const params = { __ow_headers: { authorization: 'Bearer abc123token' } };
445
+ const owTokenInfo = BearerToken.extract(params);
446
+ console.log(owTokenInfo); // Same output format as above
447
+ ```
448
+
449
+ **Direct Token Analysis**
450
+ ```typescript
451
+ const directInfo = BearerToken.info('jwt-token-string');
452
+ if (directInfo.isValid) {
453
+ console.log(`Token expires at: ${directInfo.expiry}`);
454
+ console.log(`Time until expiry: ${directInfo.timeUntilExpiry}ms`);
455
+ } else {
456
+ console.log('Token is invalid or expired');
351
457
  }
352
458
  ```
353
459
 
460
+ **Methods:**
461
+ - `extract(headersOrParams)` - Extracts Bearer token from headers or OpenWhisk params
462
+ - `info(token)` - Analyzes token string and returns validation/expiry details
463
+
354
464
  #### `InfiniteLoopBreaker`
355
465
  Detect and prevent infinite loops in event-driven applications.
356
466
 
@@ -650,9 +760,4 @@ IO_WORKSPACE_ID=workspace-id
650
760
 
651
761
  ## License
652
762
 
653
- See the [LICENSE](https://github.com/adobe-commerce/aio-toolkit/blob/main/LICENSE) file for license rights and limitations.
654
-
655
- ## Support
656
-
657
- - **Documentation**: Full API documentation available in TypeScript definitions
658
- - **Package**: [npm package page](https://www.npmjs.com/package/@adobe-commerce/aio-toolkit)
763
+ See the LICENSE file (in package) for license rights and limitations.