@adobe-commerce/aio-services-kit

Overview

A comprehensive TypeScript services kit for Adobe App Builder applications providing REST endpoint services implementation for Adobe Commerce APIs, standardized service patterns, and robust backend development tools with 100% test coverage.

Installation

npm install @adobe-commerce/aio-services-kit

Usage

The services kit is organized into framework utilities and Adobe Commerce service modules:

🛠️ Framework Components

Core infrastructure for building and consuming Adobe Commerce REST APIs

ApiResponse

Standardized success/error response handling with Adobe Commerce error format support.

import { ApiResponse } from '@adobe-commerce/aio-services-kit';

// Create success response
const success = ApiResponse.success(data);
// { success: true, data: [...] }

// Create error response
const error = ApiResponse.error(errorResponse);
// { success: false, error: "formatted message", code: 422 }

// Create fallback error
const fallback = ApiResponse.fallbackError('Something went wrong', 500);

// Check if response is an error
if (ApiResponse.isError(response.body)) {
  // Handle error
}

SearchCriteriaBuilder

Fluent API for building complex search queries with filters, sorting, and pagination.

import { SearchCriteriaBuilder } from '@adobe-commerce/aio-services-kit';

const criteria = new SearchCriteriaBuilder()
  // Add filters
  .addFilter('status', 1, 'eq')
  .addFilter('price', 100, 'gt')
  .addFilter('category_id', [1, 2, 3], 'in')
  
  // Add sorting
  .addSortOrder('created_at', 'DESC')
  .addSortOrder('name', 'ASC')
  
  // Add pagination
  .setPageSize(20)
  .setCurrentPage(1)
  
  // Add field selection
  .addField('id')
  .addField('sku')
  .addField('name')
  
  // Create search criteria
  .create();

Supported Condition Types:

• eq, neq - Equal / Not equal
• gt, gteq - Greater than / Greater than or equal
• lt, lteq - Less than / Less than or equal
• in, nin - In array / Not in array
• null, notnull - Is null / Is not null
• like - Like pattern matching

🏪 Commerce Services

Complete Adobe Commerce API integration with chainable services

AdobeCommerceService

Top-level service orchestrator providing access to all Adobe Commerce operations.

import { AdobeCommerceService } from '@adobe-commerce/aio-services-kit';

// Initialize service with your Adobe Commerce client
const commerce = new AdobeCommerceService(adobeCommerceClient);

// Access service modules
const catalogService = commerce.catalog();
const eventService = commerce.event();
const checkoutService = commerce.checkout();
const configService = commerce.configuration();

Catalog Services

ProductService - Complete product management:

const productService = commerce.catalog().product();

// List products with search criteria
const products = await productService.list(
  new SearchCriteriaBuilder()
    .addFilter('status', 1, 'eq')
    .addFilter('visibility', 4, 'eq')
    .setPageSize(20)
    .create()
);

// Get product by SKU
const product = await productService.get('PRODUCT-SKU-001');

// Create new product
const result = await productService.create({
  sku: 'NEW-PRODUCT',
  name: 'New Product',
  price: 99.99,
  type_id: 'simple',
  attribute_set_id: 4,
  status: 1,
  visibility: 4
});

// Update product
const updated = await productService.update('PRODUCT-SKU-001', {
  price: 89.99,
  name: 'Updated Product Name'
});

// Delete product
const deleted = await productService.delete('PRODUCT-SKU-001');

ProductAttributeService - Manage product attributes:

const attributeService = commerce.catalog().product().attribute();

// List all attributes
const attributes = await attributeService.list();

// List with search criteria
const filtered = await attributeService.list(
  new SearchCriteriaBuilder()
    .addFilter('is_user_defined', 1, 'eq')
    .create()
);

// Get specific attribute
const attribute = await attributeService.get('color');

// Create attribute
const created = await attributeService.create({
  attribute_code: 'custom_attr',
  frontend_label: 'Custom Attribute',
  frontend_input: 'text',
  is_required: false
});

// Update attribute
const updated = await attributeService.update('custom_attr', {
  frontend_label: 'Updated Label'
});

// Delete attribute
const deleted = await attributeService.delete('custom_attr');

ConfigurableProductService - Manage configurable products:

const configurableService = commerce.catalog().product().configurable();

// Options Management
const optionsService = configurableService.options();

// List all options
const options = await optionsService.list('CONF-PRODUCT-001');

// Get specific option
const option = await optionsService.get('CONF-PRODUCT-001', 123);

// Create new option
await optionsService.create('CONF-PRODUCT-001', {
  attribute_id: 93,
  label: 'Color',
  position: 0,
  values: [
    { value_index: 0 },
    { value_index: 1 }
  ]
});

// Update option
await optionsService.update('CONF-PRODUCT-001', 123, {
  label: 'Updated Color'
});

// Delete option
await optionsService.delete('CONF-PRODUCT-001', 123);

// Children Management
const childrenService = configurableService.children();

// List all children
const children = await childrenService.list('CONF-PRODUCT-001');

// Add child product
await childrenService.add('CONF-PRODUCT-001', 'CHILD-SKU-001');

// Remove child product
await childrenService.remove('CONF-PRODUCT-001', 'CHILD-SKU-001');

InventoryService - Manage Multi-Source Inventory (MSI):

const inventoryService = commerce.catalog().product().inventory();

// Source Items Management
const sourceItemService = inventoryService.sourceItems();

// List all source items
const sourceItems = await sourceItemService.list();

// List with search criteria
const filtered = await sourceItemService.list(
  new SearchCriteriaBuilder()
    .addFilter('sku', 'PRODUCT-SKU', 'eq')
    .addFilter('source_code', 'default', 'eq')
    .create()
);

// Create source items (batch operation)
const created = await sourceItemService.create([
  {
    sku: 'PRODUCT-SKU-001',
    source_code: 'default',
    quantity: 100,
    status: 1  // 1 = In Stock, 0 = Out of Stock
  },
  {
    sku: 'PRODUCT-SKU-002',
    source_code: 'warehouse-1',
    quantity: 50,
    status: 1
  }
]);

// Delete source items (batch operation)
const deleted = await sourceItemService.delete([
  {
    sku: 'PRODUCT-SKU-001',
    source_code: 'default'
  }
]);

Event Services

EventService - Comprehensive event management:

const eventService = commerce.event();

// Configuration
await eventService.configuration().update({
  enabled: true,
  merchant_id: 'merchant123',
  environment_id: 'env456'
});

// Subscriptions
const subscriptionService = eventService.subscription();

// List all subscriptions
const subscriptions = await subscriptionService.list();

// Create subscription
await subscriptionService.create({
  name: 'observer.catalog_product_save_after',
  destination: 'commerce.catalog.product.updated',
  fields: [
    { name: 'sku', converter: 'string' }
  ]
});

// Create with force flag to overwrite existing
await subscriptionService.create(subscriptionData, true);

// Update subscription
await subscriptionService.update('subscription-name', {
  enabled: false
});

// Delete subscription
await subscriptionService.delete('subscription-name');

// Providers
const providerService = eventService.provider();

// List all providers
const providers = await providerService.list();

// Get specific provider
const provider = await providerService.get('provider-id');

// Create provider
await providerService.create({
  provider_id: 'adobe_io',
  instance_id: 'instance_123',
  label: 'Adobe I/O Events',
  description: 'Adobe I/O Events provider'
});

// Delete provider
await providerService.delete('provider-id');

// Supported events
const supportedEvents = await eventService.supportedList();

Configuration Services

StoreService - Store configuration management:

const storeService = commerce.configuration().store();

// Get all websites
const websites = await storeService.websites();
// Response: { success: true, data: [...] }

// Get all store views
const storeViews = await storeService.storeViews();

// Get all store groups
const storeGroups = await storeService.storeGroups();

// Get all store configurations
const allConfigs = await storeService.storeConfigs();

// Get specific store configs by code
const configs = await storeService.storeConfigs(['default', 'en', 'fr']);

Checkout Services

OopeShippingCarrierService - Out-of-process shipping carrier management:

const carrierService = commerce.checkout().outOfProcess().shippingCarrier();

// List all carriers
const carriers = await carrierService.list();

// Get carrier by code
const carrier = await carrierService.getByCode('custom_carrier');

// Create carrier
await carrierService.create({
  carrier_code: 'custom_carrier',
  carrier_title: 'Custom Carrier',
  active: true
});

// Update carrier
await carrierService.update({
  carrier_code: 'custom_carrier',
  carrier_title: 'Updated Carrier'
});

// Delete carrier
await carrierService.deleteByCode('custom_carrier');

📦 Type Safety

Full TypeScript support with comprehensive type definitions:

import type {
  Product,
  ProductResponse,
  ProductAttribute,
  ProductAttributeResponse,
  Website,
  WebsiteResponse,
  StoreView,
  StoreViewResponse,
  EventSubscription,
  EventSubscriptionResponse,
  OopeShippingCarrier,
  OopeShippingCarrierResponse
} from '@adobe-commerce/aio-services-kit';

// All responses are properly typed
const result: ProductResponse = await productService.get('SKU-001');
if (result.success && result.data) {
  const product: Product = result.data;
  console.log(product.name, product.price);
}

License

See the LICENSE file for license rights and limitations.