App Management helpers

Once an app is associated with an Adobe Commerce instance through App Management, @adobe/aio-commerce-lib-app exposes a set of helpers you can call from any runtime action: connecting to the associated Commerce instance, publishing a configured I/O Event, and handling the errors those helpers can throw. This page describes each helper and how to use it. You don't need custom storage or to thread parameters through every layer of the call stack.

data-variant=info

data-slots=text

Connect to the associated Commerce instance

@adobe/aio-commerce-lib-app stores the Commerce instance an app is associated with, so any runtime action can retrieve it or call the Commerce API without custom storage.

How association is stored

Every app generated with @adobe/aio-commerce-lib-app includes a standalone association runtime action alongside app-config. App Management calls it automatically during the association lifecycle: you don't call it yourself.

• During association: stores the Commerce instance's baseUrl and env ("saas" or "paas").
• During unassociation: clears the stored data.

data-variant=info

data-slots=text

Two helpers are exported from @adobe/aio-commerce-lib-app to read that stored data back:

Both throw AssociationRecordNotFoundError if the app is not currently associated, was unassociated, or was associated by an older SDK that did not store this data. See Handle errors.

Get a ready-to-use client

The getCommerceClient method builds the base URL and flavor from the stored association data; you supply the resolved IMS auth. App Management requires IMS, so the auth parameter accepts only IMS auth: resolve it with resolveImsAuthParams (available since @adobe/aio-commerce-lib-auth version 1.0.1) from @adobe/aio-commerce-lib-auth, or pass an ImsAuthProvider built with getImsAuthProvider or forwardImsAuthProvider. The optional fetchOptions (ky options such as headers, timeout, or retry) are forwarded to the underlying client.

import { getCommerceClient } from "@adobe/aio-commerce-lib-app";
import { resolveImsAuthParams } from "@adobe/aio-commerce-lib-auth";

export async function main(params) {
  const client = await getCommerceClient(resolveImsAuthParams(params));
  const products = await client.get("products").json();
}

Get the raw instance data

Use getCommerceInstance when you only need the metadata: for example, for logging or to build a custom client.

import { getCommerceInstance } from "@adobe/aio-commerce-lib-app";

export async function main() {
  const instance = await getCommerceInstance();

  // instance.baseUrl: Commerce API base URL
  // instance.env: "saas" | "paas"
}

Handle the unassociated state

Wrap the call in try/catch to respond gracefully when the app isn't associated yet:

import { badRequest, ok } from "@adobe/aio-commerce-lib-core/responses";
import {
  AssociationRecordNotFoundError,
  getCommerceClient,
} from "@adobe/aio-commerce-lib-app";
import { resolveImsAuthParams } from "@adobe/aio-commerce-lib-auth";

export async function main(params) {
  try {
    const client = await getCommerceClient(resolveImsAuthParams(params));
    return ok({ body: await client.get("products").json() });
  } catch (error) {
    if (error instanceof AssociationRecordNotFoundError) {
      return badRequest({
        body: { message: "App is not associated with a Commerce instance." },
      });
    }
    throw error;
  }
}

Publish a configured event

Runtime actions can publish a custom I/O Event by referencing the provider and event exactly as declared in the eventing section of app.commerce.config. At installation time, the SDK writes each configured provider's I/O Events ID and event codes to system storage. The publishEvent function resolves those automatically by key and name, then publishes the event.

The publishEvent(params) function takes:

data-variant=info

data-slots=text

For example, declare an external provider with key: "order-events" and an event named order.created in app.commerce.config (see Events and Provider configuration):

import { defineConfig } from "@adobe/aio-commerce-lib-app/config";

export default defineConfig({
  metadata: {
    // ...
  },
  eventing: {
    external: [
      {
        provider: {
          key: "order-events",
          label: "Order Events",
          description: "Events published when an order changes",
        },
        events: [
          {
            name: "order.created",
            label: "Order Created",
            description: "Triggered when a new order is created",
            runtimeActions: ["my-package/handle-order-created"],
          },
        ],
      },
    ],
  },
});

A runtime action then publishes it by referencing the same key and event name:

import { publishEvent } from "@adobe/aio-commerce-lib-app";
import { createAdobeIoEventsApiClient } from "@adobe/aio-commerce-lib-events";
import { resolveImsAuthParams } from "@adobe/aio-commerce-lib-auth";

export async function main(params) {
  const client = createAdobeIoEventsApiClient({
    auth: resolveImsAuthParams(params),
    config: { ingressBaseUrl: params.AIO_EVENTS_INGRESS_BASE_URL },
  });

  await publishEvent({
    client,
    provider: "order-events",
    event: "order.created",
    payload: { orderId: "100000123", total: 149.99 },
  });
}

Resolve an event's I/O Events code ahead of time

The resolveIoEventCode(appId, eventName, providerType) function computes the same event code that publishEvent sends, matching the prefixing rules used at installation time. This is useful when a caller needs to know an event's code in advance: for example, to match it against an incoming I/O Event.

import { resolveIoEventCode } from "@adobe/aio-commerce-lib-app";

resolveIoEventCode("my-app", "observer.order_placed", "commerce");
// => "com.adobe.commerce.my_app.observer.order_placed"

resolveIoEventCode("my-app", "webhook.received", "external");
// => "my_app.webhook.received"

Instead of hardcoding appId, read it from the generated #app.commerce.config import:

import { resolveIoEventCode } from "@adobe/aio-commerce-lib-app";
import appConfig from "#app.commerce.config";

const eventCode = resolveIoEventCode(appConfig.metadata.id, "order.created", "external");

Handle errors

@adobe/aio-commerce-lib-app exports five typed error classes for the helpers on this page. PublishEventError is the base class for the three publishEvent errors, so you can catch it alone to handle any publish failure, or narrow with instanceof on the specific subclass.

import {
  EventNotFoundError,
  EventsDataNotInitializedError,
  ProviderNotFoundError,
  PublishEventError,
  publishEvent,
} from "@adobe/aio-commerce-lib-app";

try {
  await publishEvent({ client, provider, event, payload });
} catch (error) {
  if (error instanceof EventsDataNotInitializedError) {
    // The app installation hasn't run, or ran with an older SDK.
  } else if (error instanceof ProviderNotFoundError) {
    // The provider key doesn't match app.commerce.config.
  } else if (error instanceof EventNotFoundError) {
    // The event name doesn't match app.commerce.config.
  } else if (error instanceof PublishEventError) {
    // Any other publish-event failure.
  } else {
    throw error;
  }
}

Related topics

• Events: Declare the eventing provider and event configuration that publishEvent and resolveIoEventCode reference.
• Business configuration > Retrieve configuration at runtime: Read or write business configuration values from a runtime action.