@adobe-commerce/aio-toolkit 1.0.0

package/README.md

@@ -0,0 +1,658 @@
+# @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.
+
+## Installation
+
+```bash
+npm install @adobe-commerce/aio-toolkit
+```
+
+## Usage
+
+The toolkit is organized into four main modules:
+
+### 🛠️ Framework Components
+
+**Core infrastructure for Adobe App Builder applications**
+
+#### `RuntimeAction`
+HTTP request handling and business logic execution for Adobe I/O Runtime.
+
+```typescript
+const {
+  RuntimeAction,
+  RuntimeActionResponse,
+  HttpMethod,
+  HttpStatus,
+} = require('@adobe-commerce/aio-toolkit');
+
+// Create a simple action
+const myAction = RuntimeAction.execute(
+  'process-user', // Action name
+  [HttpMethod.POST], // Allowed HTTP methods
+  ['userId'], // Required parameters
+  ['authorization'], // Required headers
+  async (params, ctx) => {
+    // Your business logic here
+    const { userId } = params;
+    const { logger } = ctx;
+
+    logger.info(`Processing request for user: ${userId}`);
+
+    // Return success response
+    return RuntimeActionResponse.success({
+      message: 'Action completed successfully',
+      userId: userId,
+    });
+  }
+);
+
+// Export for Adobe I/O Runtime
+exports.main = myAction;
+```
+
+#### `EventConsumerAction`
+Event-driven processing for Adobe I/O Events with automatic validation.
+
+```typescript
+const { 
+  EventConsumerAction,
+  RuntimeActionResponse,
+  HttpStatus
+} = require('@adobe-commerce/aio-toolkit');
+
+// Create a simple event consumer
+const myEventConsumer = EventConsumerAction.execute(
+  'commerce-event-handler',
+  ['eventType'], // Required parameters
+  ['x-adobe-signature'], // Required headers
+  async (params, ctx) => {
+    const { eventType } = params;
+    const { logger } = ctx;
+
+    logger.info(`Processing event: ${eventType}`);
+
+    // Process the event
+    await processCommerceEvent(eventType, params);
+
+    // Return success response
+    return RuntimeActionResponse.success({
+      message: 'Event processed successfully',
+      eventType: eventType,
+      processedAt: new Date().toISOString()
+    });
+  }
+);
+
+// Export for Adobe I/O Runtime
+exports.main = myEventConsumer;
+```
+
+#### `GraphQlAction`
+GraphQL server implementation with schema validation and introspection control.
+
+```typescript
+const { GraphQlAction } = require('@adobe-commerce/aio-toolkit');
+
+const schema = `
+  type Query {
+    hello: String
+    user(id: ID!): User
+  }
+  
+  type User {
+    id: ID!
+    name: String!
+    email: String!
+  }
+`;
+
+const resolvers = async ctx => {
+  const { logger } = ctx;
+
+  return {
+    hello: () => 'Hello, World!',
+    user: ({ id }) => {
+      logger.debug(`Fetching user: ${id}`);
+      return {
+        id,
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+    }
+  };
+};
+
+// Create and export GraphQL endpoint
+exports.main = GraphQlAction.execute(schema, resolvers);
+```
+
+#### `OpenWhisk` & `OpenWhiskAction`
+OpenWhisk client for serverless action invocation and integration. OpenWhisk action wrapper with enhanced logging and error handling.
+
+```typescript
+const { OpenWhisk, OpenwhiskAction, RuntimeActionResponse } = require('@adobe-commerce/aio-toolkit');
+
+// Invoke another action
+const invokeAction = async (params) => {
+  try {
+    // Initialize OpenWhisk client
+    const openwhisk = new Openwhisk(params.API_HOST, params.API_AUTH)
+
+    const result = await openwhisk.execute('hello-world', {
+      name: 'World'
+    });
+    
+    console.log('Action result:', result);
+    return result;
+  } catch (error) {
+    console.error('Action invocation failed:', error);
+    throw error;
+  }
+};
+
+// Simple action with logging
+const helloWorldAction = OpenwhiskAction.execute('hello-world', async (params, ctx) => {
+  const { logger } = ctx;
+  const { name = 'World' } = params;
+
+  logger.info(`Greeting request for: ${name}`);
+
+  const message = `Hello, ${name}!`;
+
+  logger.info(`Generated greeting: ${message}`);
+
+  return RuntimeActionResponse.success({
+    message,
+    timestamp: new Date().toISOString(),
+    action: 'hello-world'
+  });
+});
+
+// Export for Adobe I/O Runtime
+exports.main = helloWorldAction;
+```
+
+#### `FileRepository`
+File-based storage with CRUD operations for Adobe I/O Runtime applications.
+
+```typescript
+const { FileRepository } = require('@adobe-commerce/aio-toolkit');
+
+// Initialize file repository
+const orderRepository = new FileRepository('orders');
+const customerRepository = new FileRepository('customers');
+
+// 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}`);
+  }
+};
+
+// 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;
+};
+
+// 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;
+};
+
+// 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}`
+        );
+    }
+  }
+);
+
+exports.main = orderManagerAction;
+```
+
+### 🏪 Commerce Components  
+
+**Adobe Commerce API integration and authentication**
+
+#### `AdobeAuth`
+Adobe IMS authentication and token management.
+
+```typescript
+const { AdobeAuth } = require('@adobe-commerce/aio-toolkit');
+
+// Get authentication token
+const token = await AdobeAuth.getToken(
+  'your-client-id',
+  'your-client-secret', 
+  'your-technical-account-id',
+  'your-technical-account-email',
+  'your-ims-org-id',
+  ['AdobeID', 'openid', 'adobeio_api'] // Scopes
+);
+
+console.log('Authentication token:', token);
+```
+
+#### `AdobeCommerceClient`
+HTTP client for Adobe Commerce API integration with multiple authentication methods.
+
+```typescript
+const { AdobeCommerceClient } = require('@adobe-commerce/aio-toolkit');
+const { Oauth1aConnection } = require('@adobe-commerce/aio-toolkit');
+
+const connection = new Oauth1aConnection(
+  'consumer-key',
+  'consumer-secret',
+  'access-token',
+  'access-token-secret',
+  logger? // Optional custom logger
+);
+
+// Create client
+const client = new AdobeCommerceClient('https://your-commerce-store.com', connection);
+
+// Make API calls
+const products = await client.get('rest/V1/products');
+const newProduct = await client.post('rest/V1/products', {}, productData);
+```
+
+### 🔗 Integration Components
+
+**External API integration and utility functions**
+
+#### `RestClient`
+HTTP client for external API integration.
+
+```typescript
+const { RestClient } = require('@adobe-commerce/aio-toolkit');
+
+const client = new RestClient();
+const response = await client.get('https://api.example.com/data', {
+  'Authorization': 'Bearer token',
+  'Content-Type': 'application/json'
+});
+```
+
+#### `BearerToken`
+Bearer token extraction and JWT analysis utility.
+
+```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);
+}
+```
+
+#### `InfiniteLoopBreaker`
+Detect and prevent infinite loops in event-driven applications.
+
+```typescript
+const { InfiniteLoopBreaker } = require('@adobe-commerce/aio-toolkit');
+
+// Basic infinite loop detection
+const isLoop = await InfiniteLoopBreaker.isInfiniteLoop({
+  keyFn: 'order-processing-key',
+  fingerprintFn: orderData,
+  eventTypes: ['order.created', 'order.updated'],
+  event: 'order.created'
+});
+
+if (isLoop) {
+  console.log('Infinite loop detected, skipping processing');
+  return;
+}
+
+// Process the event
+await processOrderEvent(orderData);
+
+// Store fingerprint to prevent future loops
+await InfiniteLoopBreaker.storeFingerPrint(
+  'order-processing-key',
+  orderData,
+  300 // 5 minutes TTL
+);
+```
+
+#### `OnboardEvents`
+Complete onboarding orchestration for Adobe I/O Events (providers, metadata, and registrations).
+
+```typescript
+const { OnboardEvents } = require('@adobe-commerce/aio-toolkit');
+
+const onboardEvents = new OnboardEvents(
+  'My E-commerce Store',
+  process.env.ADOBE_CONSUMER_ID!,
+  process.env.ADOBE_PROJECT_ID!,
+  process.env.ADOBE_WORKSPACE_ID!,
+  process.env.ADOBE_API_KEY!,
+  process.env.ADOBE_ACCESS_TOKEN!
+);
+
+const basicOnboardingExample = async () => {
+  const input = {
+    providers: [
+      {
+        key: 'ecommerce-provider',
+        label: 'E-commerce Events Provider',
+        description: 'Provider for e-commerce platform events',
+        docsUrl: 'https://docs.mystore.com/events',
+        registrations: [
+          {
+            key: 'order-events',
+            label: 'Order Events Registration',
+            description: 'Registration for order-related events',
+            events: [
+              {
+                eventCode: 'com.mystore.order.placed',
+                runtimeAction: 'mystore/order-placed-handler',
+                deliveryType: 'webhook',
+                sampleEventTemplate: {
+                  orderId: 'ord_123456',
+                  customerId: 'cust_789',
+                  totalAmount: 99.99,
+                  currency: 'USD',
+                  status: 'placed',
+                  timestamp: '2023-01-01T12:00:00Z'
+                }
+              },
+              {
+                eventCode: 'com.mystore.order.shipped',
+                runtimeAction: 'mystore/order-shipped-handler',
+                deliveryType: 'journal',
+                sampleEventTemplate: {
+                  orderId: 'ord_123456',
+                  trackingNumber: 'TN123456789',
+                  carrier: 'UPS',
+                  shippedAt: '2023-01-02T10:00:00Z'
+                }
+              }
+            ]
+          }
+        ]
+      }
+    ]
+  };
+
+  try {
+    const result = await onboardEvents.process(input);
+    
+    console.log('Onboarding completed successfully!');
+    console.log(`Providers: ${result.createdProviders.length} processed`);
+    console.log(`Events: ${result.createdEvents.length} processed`);
+    console.log(`Registrations: ${result.createdRegistrations.length} processed`);
+    
+    // Check results
+    result.createdProviders.forEach(provider => {
+      if (provider.created) {
+        console.log(`✅ Created provider: ${provider.provider.label}`);
+      } else if (provider.skipped) {
+        console.log(`⏭️ Skipped existing provider: ${provider.provider.label}`);
+      } else {
+        console.log(`❌ Failed to create provider: ${provider.error}`);
+      }
+    });
+    
+    return result;
+  } catch (error) {
+    console.error('Onboarding failed:', error.message);
+    return null;
+  }
+};
+
+basicOnboardingExample();
+```
+
+### 📡 I/O Events Components
+
+**Adobe I/O Events management and orchestration**
+
+#### `EventMetadataManager`
+Manage event metadata for Adobe I/O Events providers.
+
+```typescript
+const { EventMetadataManager } = require('@adobe-commerce/aio-toolkit');
+
+const manager = new EventMetadataManager({
+  apiKey: 'your-api-key',
+  accessToken: 'your-access-token',
+  consumerId: 'your-consumer-id',
+  projectId: 'your-project-id',
+  workspaceId: 'your-workspace-id'
+});
+
+// Create event metadata
+const eventMetadata = await manager.create({
+  providerId: 'your-provider-id',
+  eventCode: 'commerce.order.created',
+  label: 'Order Created',
+  description: 'Triggered when a new order is created in the commerce system',
+  sampleEventTemplate: {
+    orderId: 'ORD-123456',
+    customerId: 'CUST-789',
+    amount: 199.99,
+    currency: 'USD',
+    items: [
+      {
+        sku: 'PRODUCT-001',
+        name: 'Premium Widget',
+        quantity: 2,
+        price: 99.99
+      }
+    ],
+    timestamp: '2023-12-01T10:30:00Z'
+  }
+});
+
+// Get event metadata
+const metadata = await manager.get('your-provider-id', 'commerce.order.created');
+
+// List all event metadata for a provider
+const allMetadata = await manager.list('your-provider-id');
+
+// Delete specific event metadata
+await manager.delete('your-provider-id', 'commerce.order.created');
+
+// Delete all event metadata for a provider
+await manager.delete('your-provider-id');
+```
+
+#### `ProviderManager`
+Manage event providers for Adobe I/O Events.
+
+```typescript
+const { ProviderManager } = require('@adobe-commerce/aio-toolkit');
+
+const manager = new ProviderManager({
+  apiKey: 'your-api-key',
+  accessToken: 'your-access-token',
+  consumerId: 'your-consumer-id',
+  projectId: 'your-project-id',
+  workspaceId: 'your-workspace-id'
+});
+
+// Create a new provider
+const provider = await manager.create({
+  label: 'E-commerce Events Provider',
+  description: 'Provides events from our e-commerce platform including orders, customers, products, and inventory updates',
+  docsUrl: 'https://docs.mystore.com/events-api',
+  providerMetadata: {
+    region: 'us-east-1',
+    environment: 'production',
+    version: '2.1.0'
+  }
+});
+
+// Get provider details
+const existingProvider = await manager.get('your-provider-id', {
+  eventmetadata: true // Include event metadata in response
+});
+
+// List all providers
+const providers = await manager.list({
+  eventmetadata: true, // Include event metadata
+  providerMetadataIds: ['provider-1', 'provider-2'] // Filter by specific providers
+});
+
+// List providers with advanced filtering
+const filteredProviders = await manager.list({
+  instanceId: 'your-instance-id',
+  providerMetadataId: 'specific-provider-metadata-id'
+});
+
+// Delete provider
+await manager.delete('your-provider-id');
+```
+
+#### `RegistrationManager`
+Manage event registrations and subscriptions for Adobe I/O Events.
+
+```typescript
+const { RegistrationManager } = require('@adobe-commerce/aio-toolkit');
+
+const manager = new RegistrationManager({
+  apiKey: 'your-api-key',
+  accessToken: 'your-access-token',
+  consumerId: 'your-consumer-id',
+  projectId: 'your-project-id',
+  workspaceId: 'your-workspace-id'
+});
+
+// Create event registration
+const registration = await manager.create({
+  name: 'Order Processing Registration',
+  description: 'Handles order-related events',
+  delivery: {
+    type: 'webhook',
+    url: 'https://your-app.com/webhook/orders'
+  },
+  eventsOfInterest: [
+    {
+      providerId: 'your-provider-id',
+      eventCode: 'commerce.order.created'
+    },
+    {
+      providerId: 'your-provider-id', 
+      eventCode: 'commerce.order.updated'
+    }
+  ]
+});
+
+// Get registration details
+const existingRegistration = await manager.get('your-registration-id');
+
+// List all registrations
+const registrations = await manager.list();
+
+// Delete registration
+await manager.delete('your-registration-id');
+```
+
+## Environment Variables
+
+Common environment variables used across components:
+
+```bash
+# Adobe commerce credentials
+COMMERCE_BASE_URL=commerce-base-url
+COMMERCE_CONSUMER_KEY=commerce-consumer-key
+COMMERCE_CONSUMER_SECRET=commerce-consumer-secret
+COMMERCE_ACCESS_TOKEN=commerce-access-token
+COMMERCE_ACCESS_TOKEN_SECRET=commerce-access-token-secret
+# Environment from DIST file
+OAUTH_BASE_URL=https://ims-na1.adobelogin.com/ims/token/
+IO_MANAGEMENT_BASE_URL=https://api.adobe.io/events/
+# OAuth configs
+# The following values can be copied from the Credential details page in AppBuilder under Organization > Project > Workspace > OAuth Server-to-Server
+OAUTH_CLIENT_ID=client-id
+OAUTH_CLIENT_SECRET=client-secret
+OAUTH_TECHNICAL_ACCOUNT_ID=technical-account-id
+OAUTH_TECHNICAL_ACCOUNT_EMAIL=technical-account-email
+OAUTH_ORG_ID=org-id
+OAUTH_SCOPES=scopes
+# OAUTH_HOST=<string>
+# Workspace configs
+# The following values can be copied from the JSON downloadable in AppBuilder from Organization > Project > Workspace
+# IO_CONSUMER corresponds to project.org.id
+# IO_PROJECT_ID corresponds to project.id
+# IO_WORKSPACE_ID corresponds to project.workspace.id
+IO_CONSUMER_ID=consumer-id
+IO_PROJECT_ID=project-id
+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)