Commerce App Storage

// Full annotated reference for a Commerce app runtime action backed by
// App Builder Database Storage (@adobe/aio-lib-db).
//
// Lifecycle (identical for web actions and event/webhook handlers):
//   resolveImsAuthParams -> getAccessToken -> init -> connect -> use collection -> ALWAYS close.
//
// Registration requirements (in src/commerce-extensibility-1/ext.config.yaml):
//   - include-ims-credentials: true   (REQUIRED — provides the IMS token below)
//   - web: "yes" for an HTTP-invokable web action; "no" for an event/webhook handler
//   - the "App Builder Data Services" API must be added to the project in the
//     Adobe Developer Console (every workspace that uses the database)
//   - the workspace database must be provisioned: declaratively via the
//     app.config.yaml database block on `aio app deploy` (CLI `aio app db
//     provision --region <r>` is the local-dev fallback)

import {
  getImsAuthProvider,
  resolveImsAuthParams,
} from "@adobe/aio-commerce-lib-auth";
import { buildErrorResponse, ok } from "@adobe/aio-commerce-lib-core/responses";
import AioLogger from "@adobe/aio-lib-core-logging";
import { init as initDb } from "@adobe/aio-lib-db";

// The connected client returned by db.connect().
type DbClient = Awaited<
  ReturnType<Awaited<ReturnType<typeof initDb>>["connect"]>
>;

export async function main(params: Record<string, unknown>) {
  const logger = AioLogger("commerce-app-storage", {
    level: (params.LOG_LEVEL as string) || "info",
  });

  // Web actions receive input directly on params; event/webhook handlers
  // receive the payload on params.data instead:
  //   const data = params.data as Record<string, unknown>;
  let client: DbClient | undefined;

  try {
    // 1. Resolve the AIO_COMMERCE_AUTH_IMS_* params injected because
    //    include-ims-credentials is true, then mint a raw access token string.
    const authProvider = getImsAuthProvider(resolveImsAuthParams(params));
    const token = await authProvider.getAccessToken();

    // 2. Initialize. region MUST match the manifest database.region.
    //    Omit it to use AIO_DB_REGION or the "amer" default.
    const db = await initDb({
      token,
      region: (params.DB_REGION as string) || "amer", // "amer" | "apac" | "emea" | "aus"
    });

    // 3. Connect — opens a session that must be closed (see finally).
    client = await db.connect();

    // 4. Select a collection (created on first write if absent).
    const records = client.collection("records");

    // --- CRUD reference ---------------------------------------------------

    // Insert one
    const inserted = await records.insertOne({
      name: "Jane Smith",
      createdAt: new Date().toISOString(),
    });

    // Insert many
    await records.insertMany([{ name: "Alice" }, { name: "Bob" }]);

    // Find one
    const one = await records.findOne({ name: "Jane Smith" });

    // Find many — returns a cursor. Iterate to bound memory.
    for await (const doc of records
      .find({ active: true })
      .project({ name: 1, _id: 0 })) {
      logger.info("record", doc);
    }
    // ...or load all at once (only for small result sets):
    // const all = await records.find({}).toArray();

    // Update one (use $set / other operators)
    await records.updateOne({ name: "Jane Smith" }, { $set: { active: true } });

    // Update many
    await records.updateMany(
      { active: { $exists: false } },
      { $set: { active: false } },
    );

    // Find and update, returning the updated document
    await records.findOneAndUpdate(
      { name: "Jane Smith" },
      { $set: { lastSeen: new Date() } },
      { returnDocument: "after" },
    );

    // Delete one / many
    await records.deleteOne({ name: "Bob" });
    await records.deleteMany({ active: false });

    // Look up a document by its _id supplied as a string:
    //   import { ObjectId } from "bson";
    //   await records.findOne({ _id: new ObjectId(idString) });

    return ok({ body: { inserted, one } });
  } catch (error) {
    // Database errors surface with name === "DbError".
    const dbError = error as {
      name?: string;
      message?: string;
      statusCode?: number;
    };
    if (dbError.name === "DbError") {
      logger.error("Database error", dbError.message);
    } else {
      logger.error("Unexpected error", error);
    }
    return buildErrorResponse(dbError.statusCode ?? 500, {
      body: { message: dbError.message ?? "Unexpected error" },
    });
  } finally {
    // 5. ALWAYS close — leaked connections exhaust resources.
    if (client) {
      await client
        .close()
        .catch((e: Error) =>
          logger.warn("Failed to close DB client", e.message),
        );
    }
  }
}

// Full annotated custom installation step for a Commerce App Management app,
// backed by App Builder Database Storage (@adobe/aio-lib-db).
//
// What it does:
//   - install:   creates the "held_orders" collection and a UNIQUE index on order_id
//   - uninstall: drops the collection to reverse the install
//
// Why a custom installation step (vs. ad-hoc setup on first request):
//   It runs exactly once when the app is installed from the Commerce Admin,
//   and the uninstall handler lets the app clean up after itself.
//
// Author the install script as an ES module with `export default` — never
// `module.exports`. The installation action loads each step via
// `import * as step from "<script>"` and reads `step.default`, so the script
// must default-export the defineCustomInstallationStep(...) result. The `script`
// path must end in .js; if you author in TypeScript, compile it and keep the
// emitted .js an ES module.
//
// Wiring (in app.commerce.config.ts) — the script path is the COMPILED .js:
//   installation: {
//     customInstallationSteps: [
//       {
//         script: "./scripts/setup-database.js",
//         name: "Set up held-orders collection",
//         description: "Creates the held_orders collection and a unique index on order_id",
//       },
//     ],
//   }
//
// Two easy mistakes this file avoids:
//   1. Resolve the IMS auth params from context.params — NOT config. config is the
//      app configuration and carries no credentials; context.params carries the
//      injected IMS credentials (AIO_COMMERCE_AUTH_IMS_*) read by
//      @adobe/aio-commerce-lib-auth.
//   2. createIndex is called ON A COLLECTION OBJECT, not with a collection-name string.

import { defineCustomInstallationStep } from "@adobe/aio-commerce-lib-app/management";
import {
  getImsAuthProvider,
  resolveImsAuthParams,
} from "@adobe/aio-commerce-lib-auth";
import { init as initDb } from "@adobe/aio-lib-db";

const COLLECTION = "held_orders";

// Open a DB client using the credentials on context.params. The caller is
// responsible for closing it (see the finally blocks below).
async function openClient(context: { params: Record<string, unknown> }) {
  // include-ims-credentials makes the AIO_COMMERCE_AUTH_IMS_* credentials available
  // on context.params; resolve them and mint a raw access token string.
  const authProvider = getImsAuthProvider(resolveImsAuthParams(context.params));
  const token = await authProvider.getAccessToken();
  const db = await initDb({
    token,
    // region MUST match the manifest database.region. Omit to use AIO_DB_REGION.
    region: (context.params.DB_REGION as string) || "amer", // "amer" | "apac" | "emea" | "aus"
  });
  return db.connect();
}

export default defineCustomInstallationStep({
  install: async (config, context) => {
    const { logger } = context;
    logger.info(`Setting up storage for ${config.metadata.displayName}...`);

    let client: Awaited<ReturnType<typeof openClient>> | undefined;
    try {
      client = await openClient(context);

      // Get the collection OBJECT first (created on first write if absent),
      // then create the index on it — never pass a collection-name string.
      const orders = client.collection(COLLECTION);
      await orders.createIndex({ order_id: 1 }, { unique: true });

      logger.info(`Created "${COLLECTION}" with a unique index on order_id`);
      return { status: "success", collection: COLLECTION };
    } catch (error) {
      if (error instanceof Error && error.name === "DbError") {
        logger.error("Database error during install", error.message);
      }
      throw error; // re-throw so the installation step fails loudly
    } finally {
      if (client) {
        await client
          .close()
          .catch((e: Error) =>
            logger.warn("Failed to close DB client", e.message),
          );
      }
    }
  },

  uninstall: async (config, context) => {
    const { logger } = context;
    logger.info(`Removing storage for ${config.metadata.displayName}...`);

    let client: Awaited<ReturnType<typeof openClient>> | undefined;
    try {
      client = await openClient(context);
      await client.collection(COLLECTION).drop();
      logger.info(`Dropped "${COLLECTION}"`);
    } finally {
      if (client) {
        await client
          .close()
          .catch((e: Error) =>
            logger.warn("Failed to close DB client", e.message),
          );
      }
    }
  },
});

{
  "skill_name": "commerce-app-storage",
  "evals": [
    {
      "id": 1,
      "prompt": "I want to persist customer feedback in my Commerce app. Add a web runtime action that stores a feedback document in App Builder Database Storage and returns the result.",
      "expected_output": "The agent installs @adobe/aio-lib-db, registers a web action (web: \"yes\") under a user package (not app-management) in src/commerce-extensibility-1/ext.config.yaml with include-ims-credentials: true, and creates a handler that resolves the injected IMS auth params with @adobe/aio-commerce-lib-auth, mints a raw access token string, calls init then connect, inserts into a collection, and closes the client in a finally block. It notes the workspace database must be provisioned (declaratively via the app.config.yaml database block on deploy, with the aio app db provision CLI as a local-dev fallback) and that the App Builder Data Services API must be added to the project in the Adobe Developer Console.",
      "assertions": [
        "The action is registered with include-ims-credentials: true",
        "The action package name is not 'app-management'",
        "The handler calls init() then connect() and obtains a collection",
        "The handler closes the client in a finally block",
        "An IMS access token is obtained via getImsAuthProvider(resolveImsAuthParams(params)).getAccessToken() from @adobe/aio-commerce-lib-auth and passed to init() as a raw string (not generateAccessToken, not token.access_token)",
        "The action is registered with web: \"yes\"",
        "Provisioning (declarative auto-provision in app.config.yaml as primary, aio app db provision CLI as local-dev fallback) and the App Builder Data Services API are mentioned"
      ]
    },
    {
      "id": 2,
      "prompt": "When an order is placed in Commerce, I want to record it in our database. The order event handler already needs to be created. Scaffold the event action and have it write the order to a collection.",
      "expected_output": "The agent scaffolds an event/webhook action (web: \"no\") registered with include-ims-credentials: true, reading the payload from params.data, and writing to a collection using the init/connect/close lifecycle. After build passes it suggests commerce-app-eventing to wire the action to the order event via runtimeActions.",
      "assertions": [
        "The action is registered with include-ims-credentials: true",
        "The handler reads the event payload from params.data",
        "The handler uses init() -> connect() -> collection write -> close() in finally",
        "The action is registered with web: \"no\"",
        "Agent mentions commerce-app-eventing (or runtimeActions) to wire the action to the event"
      ]
    },
    {
      "id": 3,
      "prompt": "Our workspace database is in emea. Add a runtime action that looks up a product by SKU from a 'products' collection, and make sure queries are efficient.",
      "expected_output": "The agent creates a handler that initializes the library with region 'emea' (matching provisioning), connects, queries the products collection by sku, and closes the client. It promotes best practices: creating an index on the queried field, using projections, and iterating cursors for large result sets.",
      "assertions": [
        "init() is called with region: \"emea\"",
        "The handler queries the products collection filtering by sku",
        "The client is closed in a finally block",
        "The agent recommends an index on the queried field and/or projections for efficiency",
        "aio app build completes without errors"
      ]
    },
    {
      "id": 4,
      "prompt": "When my Commerce app installs, create a 'held_orders' collection with a unique index on order_id so duplicate holds are rejected. Set it up as part of the app installation, not on first request.",
      "expected_output": "The agent authors a custom installation step with defineCustomInstallationStep (install handler, ideally with an uninstall that drops the collection), exported as an ES module default export (export default, not module.exports), resolves the IMS auth params from context.params via @adobe/aio-commerce-lib-auth and mints a raw access token string, connects, gets the collection object and calls createIndex({ order_id: 1 }, { unique: true }) on it, and closes the client in a finally block. It wires the script into app.commerce.config.ts under installation.customInstallationSteps with a .js script path, a unique name, and a description.",
      "assertions": [
        "The step is defined with defineCustomInstallationStep from @adobe/aio-commerce-lib-app/management",
        "The IMS token is obtained via getImsAuthProvider(resolveImsAuthParams(context.params)).getAccessToken() from @adobe/aio-commerce-lib-auth (from context.params, not config; not generateAccessToken)",
        "createIndex is called on a collection object with { order_id: 1 } and { unique: true }",
        "The client is closed in a finally block",
        "The step is registered under installation.customInstallationSteps in app.commerce.config.ts with a .js script path, a name, and a description",
        "The install script is authored as an ES module using export default (not module.exports / CommonJS)"
      ]
    },
    {
      "id": 5,
      "prompt": "My Commerce app is extension-only (no application runtime actions) and uses App Builder Database Storage. After aio app deploy the workspace database isn't provisioned. Configure it so the database is auto-provisioned on deploy.",
      "expected_output": "The agent explains that declarative auto-provision is skipped for extension-only apps because the application runtime manifest has no runtime action, and applies the workaround in app.config.yaml: an empty packages map (packages: {}) under application.runtimeManifest plus a post-app-build hook running mkdir -p dist/application/actions, alongside the database auto-provision block with a region. It may also mention the aio app db provision CLI as a local-dev fallback.",
      "assertions": [
        "Identifies that auto-provision is skipped because the app has no application runtime action",
        "Adds packages: {} under application.runtimeManifest",
        "Adds a post-app-build hook running mkdir -p dist/application/actions",
        "Keeps the database auto-provision block with a region",
        "References the aio app db provision CLI as a local-dev fallback"
      ]
    },
    {
      "id": 6,
      "prompt": "Add a web action that stores records in App Builder Database Storage. My repo has an app.commerce.config.ts at the root, but I haven't initialized the project yet — there's no src/commerce-extensibility-1/ directory and no node_modules.",
      "expected_output": "The agent recognizes that although the config exists, the project is not initialized (no src/commerce-extensibility-1/ or node_modules), so it runs npx @adobe/aio-commerce-lib-app init before proceeding — without overwriting the existing config. Only after the project is initialized does it install @adobe/aio-lib-db and scaffold the storage web action.",
      "assertions": [
        "The agent detects the project is not initialized despite the config being present",
        "The agent runs npx @adobe/aio-commerce-lib-app init before doing storage work",
        "The existing app.commerce.config.ts is not overwritten",
        "Storage work (installing @adobe/aio-lib-db, scaffolding the action) proceeds only after initialization"
      ]
    }
  ]
}