@adobe-commerce/aio-toolkit 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,93 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-03-30
+
+### ✨ Features
+
+- **feat(abdb): Add `AbdbColumn` and `AbdbCollection` framework components**
+
+  Two new framework components that provide a typed schema definition layer and managed database connectivity via `@adobe/aio-lib-db`.
+
+#### `AbdbColumn`
+
+Immutable field definition class for describing a single column in an ABDB document schema.
+
+- Supports four value types: `STRING`, `NUMBER`, `BOOLEAN`, `DATETIME`
+- Comprehensive type coercion rules — accepts numeric strings, `"true"/"false"` strings, ISO 8601 date strings, finite numeric timestamps, and `Date` objects
+- Required field enforcement via `isRequired` flag
+- `validate(value)` — throws on the first type or requiredness violation
+- `clone(overrides?)` — derives a new immutable instance with overridden fields
+- `toJSON()` — serializes to a plain `AbdbColumnJson` object
+- Fully immutable after construction (`Object.freeze`)
+- Exhaustive `switch` guard via TypeScript `never` — compile-time safety if a new type is added without updating the validator
+
+#### `AbdbCollection`
+
+Named schema container with fluent column registration, validation, and a managed Adobe I/O DB lifecycle.
+
+- `addColumn(name, type, description?, isRequired?)` — **positional form** (backward-compatible short syntax)
+- `addColumn(name, type, options?)` — **options-object form** — no `undefined` placeholder needed to set only `isRequired`
+- `getColumn(name)` — O(1) single-column lookup; returns `undefined` if not found
+- `hasColumn(name)` — O(1) existence check
+- `getColumns()` — defensive copy in insertion order
+- `validate(record)` — fail-fast; throws on the **first** failing column
+- `validateAll(record)` — collects **all** column errors; returns `string[]` — ideal for API error responses
+- `run<T>(callback, token, region?)` — opens `@adobe/aio-lib-db` connection, invokes callback with `(collection, client)`, closes in `finally`
+
+#### Types exported
+
+| Type | Description |
+|---|---|
+| `AbdbColumnType` | String enum: `STRING \| NUMBER \| BOOLEAN \| DATETIME` |
+| `AbdbColumnOptions` | Constructor input shape for `AbdbColumn` |
+| `AbdbColumnJson` | `toJSON()` output shape |
+| `AddColumnOptions` | `Omit<AbdbColumnOptions, 'name' \| 'type'>` — options-object form for `addColumn` |
+| `AbdbCollectionCallback` | Constructor setup callback `(collection: AbdbCollection) => void` |
+| `AbdbRunCallback<T>` | Async work callback for `run()` |
+
+## [1.1.1] - 2026-03-28
+
+### 🐛 Bug Fixes
+
+- **Fixed `ERESOLVE` installation failures introduced in v1.1.0**
+  - `v1.1.0` moved `cloudevents`, `dotenv`, `node-fetch`, and `openwhisk` to `peerDependencies` to avoid duplicate module installs
+  - This caused hard `ERESOLVE` errors for any client that had one of those packages installed at a different major version (e.g. `cloudevents@4.x` vs the required `>=8.0.0`)
+  - Root cause: `peerDependenciesMeta.optional: true` only suppresses the "not installed" warning — it does **not** suppress `ERESOLVE` when the package IS installed at an incompatible version
+  - Fix: moved these four packages back to `dependencies` where they belong
+
+### 🔧 Dependency Changes
+
+| Package | v1.1.0 | v1.1.1 | Reason |
+|---|---|---|---|
+| `cloudevents` | `peerDependencies` (optional) | `dependencies` | Clients have v4.x — incompatible with `>=8.0.0` range; duplicate copies harmless (stateless) |
+| `dotenv` | `peerDependencies` (optional) | `dependencies` | Stateless — just sets `process.env`; two copies are harmless |
+| `node-fetch` | `peerDependencies` (optional) | `dependencies` | Stateless HTTP function — no singleton, no shared state |
+| `openwhisk` | `peerDependencies` (optional) | `dependencies` | Creates client instances per call — no global singleton |
+
+### 📝 Peer Dependency Philosophy
+
+Only packages that maintain **shared singleton state** between the toolkit and the client application belong in `peerDependencies`. Stateless utilities where duplicate copies are functionally harmless must stay in `dependencies` to avoid blocking installation.
+
+Packages that remain in `peerDependencies` as **required** peers (all five are unconditionally imported at package load time):
+
+| Package | Why it must be a peer dep |
+|---|---|
+| `@adobe/aio-sdk` | Singleton services — logger, config, state shared across the app |
+| `graphql` | Schema registry singleton — two copies cause `instanceof` and type failures |
+| `@adobe/aio-lib-ims` | Token cache and auth context must be a single shared instance |
+| `@adobe/aio-lib-telemetry` | Single telemetry pipeline — two copies split traces and logs |
+| `@opentelemetry/resources` | Resource object tied to the telemetry pipeline instance |
+
+### 💡 Migration Guide
+
+```bash
+# Upgrade from v1.1.0 — no code changes required
+npm install @adobe-commerce/aio-toolkit@1.1.1
+```
+
+---
+
 ## [1.1.0] - 2026-03-27
 
 ### ⚠️ Breaking Changes

package/README.md

@@ -7,9 +7,16 @@ A comprehensive TypeScript toolkit for Adobe App Builder applications providing
 ## Installation
 
 ```bash
-npm install @adobe-commerce/aio-toolkit
+npm install @adobe-commerce/aio-toolkit \
+  @adobe/aio-sdk \
+  @adobe/aio-lib-ims \
+  @adobe/aio-lib-telemetry \
+  @opentelemetry/resources \
+  graphql
 ```
 
+> **App Builder projects** already include `@adobe/aio-sdk`, `@adobe/aio-lib-ims`, and `graphql` — you only need to add the missing ones. See [Dependency Resolution](#dependency-resolution) for details.
+
 ## Usage
 
 The toolkit is organized into five main modules:
@@ -668,6 +675,118 @@ This approach provides:
 - **Flexible ID management**: Support for explicit IDs, payload IDs, and auto-generation
 - **Automatic sanitization**: IDs are cleaned to ensure file system compatibility
 
+#### `AbdbColumn` & `AbdbCollection`
+
+Typed schema definition and managed database connectivity via `@adobe/aio-lib-db`.
+
+The recommended pattern is to create a dedicated collection class per entity by extending `AbdbCollection`, then use it directly inside runtime actions.
+
+##### 1. Define a custom collection
+
+Create a reusable collection class that declares the schema once:
+
+```javascript
+// src/collections/UserCollection.js
+'use strict';
+
+const { AbdbCollection, AbdbColumnType } = require('@adobe-commerce/aio-toolkit');
+
+/**
+ * ABDB collection for the `users` table.
+ *
+ * Columns:
+ * - `first_name` (STRING, required)
+ * - `last_name`  (STRING, required)
+ * - `email`      (STRING, required)
+ */
+class UserCollection extends AbdbCollection {
+  constructor() {
+    super('users', (c) => {
+      c.addColumn('first_name', AbdbColumnType.STRING, 'First name', true)
+       .addColumn('last_name',  AbdbColumnType.STRING, 'Last name',  true)
+       .addColumn('email',      AbdbColumnType.STRING, 'Email address', true);
+    });
+  }
+}
+
+module.exports = UserCollection;
+```
+
+##### 2. Use it in a runtime action
+
+```javascript
+const { HttpMethod, RuntimeAction, RuntimeActionResponse } = require('@adobe-commerce/aio-toolkit');
+const UserCollection = require('@lib/UserCollection');
+
+exports.main = RuntimeAction.execute(
+  'users-create',
+  [HttpMethod.POST],
+  ['first_name', 'last_name', 'email'],
+  ['Authorization'],
+  async (params, ctx) => {
+    const { first_name, last_name, email } = params;
+    const { logger } = ctx;
+
+    const accessToken = /* extract from params / IMS */;
+
+    const users = new UserCollection();
+
+    // Fail-fast validation — throws before touching the DB
+    users.validate({ first_name, last_name, email });
+
+    // Open DB connection, run the operation, close in finally
+    const result = await users.run(async (collection) => {
+      return await collection.insertOne({ first_name, last_name, email });
+    }, accessToken);
+
+    logger.info(`User inserted: ${result.insertedId}`);
+
+    return RuntimeActionResponse.success(result);
+  }
+);
+```
+
+##### 3. API surface reference
+
+**`addColumn` call forms:**
+
+```javascript
+// Positional (short form) — description and isRequired are optional positional args
+c.addColumn('email', AbdbColumnType.STRING, 'Email address', true);
+
+// Options-object form — no undefined placeholder needed when setting only one option
+c.addColumn('email', AbdbColumnType.STRING, { isRequired: true });
+c.addColumn('note',  AbdbColumnType.STRING, { description: 'An optional note' });
+```
+
+**Supported types (`AbdbColumnType`):**
+
+| Value | Accepts |
+|---|---|
+| `STRING` | Primitive string |
+| `NUMBER` | Finite number, or numeric string (e.g. `"3.14"`) |
+| `BOOLEAN` | `true`/`false`, or `"true"`/`"false"` (case-insensitive) |
+| `DATETIME` | `Date`, finite timestamp (ms), or ISO 8601 string |
+
+**Validation strategies:**
+
+```javascript
+// Fail-fast — throws on the first error (use before DB writes)
+users.validate({ first_name: 'Jane', last_name: 'Doe', email: 'jane@example.com' });
+
+// Collect all errors — ideal for API validation responses
+const errors = users.validateAll({ first_name: '', email: 'not-an-email' });
+// errors → ['"first_name" expects a string', '"last_name" is required']
+```
+
+**Column introspection:**
+
+```javascript
+users.hasColumn('email');          // true
+users.getColumn('email');          // AbdbColumn instance (or undefined)
+users.getColumns();                // Map<string, AbdbColumn> in insertion order
+```
+
 ### 🏪 Commerce Components  
 
 **Adobe Commerce API integration and authentication**
@@ -1744,6 +1863,105 @@ COMMERCE_ACCESS_TOKEN=commerce-access-token
 COMMERCE_ACCESS_TOKEN_SECRET=commerce-access-token-secret
 ```
 
+## Dependency Resolution
+
+This toolkit carefully manages its dependency tree to avoid conflicts with packages already installed in your App Builder project.
+
+### How dependencies are split
+
+#### `dependencies` — bundled with the toolkit
+
+Packages installed directly by the toolkit that are either unique to it, or are stateless utilities where having two copies causes no functional harm:
+
+| Package | Reason |
+|---|---|
+| `@adobe-commerce/aio-services-kit` | Companion package — not used by client projects directly |
+| `cloudevents` | Stateless event constructor — duplicate copies are harmless |
+| `dotenv` | Stateless — only sets `process.env`; two copies are harmless |
+| `got` | Internal HTTP client for Commerce API — not exposed externally |
+| `node-fetch` | Stateless HTTP function — no shared state |
+| `oauth-1.0a` | Internal OAuth 1.0a request signing — not exposed externally |
+| `openwhisk` | Creates client instances per call — no global singleton |
+| `uuid` | Pure stateless function — no conflict possible |
+| `yaml` | Stateless YAML parser — no shared state |
+
+#### `peerDependencies` — must use your project's copy
+
+Packages that maintain **singleton state or shared registries** — if two copies exist (one in the toolkit, one in your project), they behave as separate instances which breaks shared behaviour:
+
+| Package | Why it must be shared |
+|---|---|
+| `@adobe/aio-sdk` | Singleton services — logger, config, state are shared across the app |
+| `graphql` | Schema registry is a singleton — `instanceof GraphQLSchema` and type checks fail with two copies |
+| `@adobe/aio-lib-ims` | Token cache and auth context must be the same shared instance |
+| `@adobe/aio-lib-telemetry` | Single telemetry pipeline — two copies split traces and logs |
+| `@opentelemetry/resources` | Resource object tied to the telemetry pipeline instance |
+
+All five are **required** — they are unconditionally imported when the package loads (`export * from './framework'` and `export * from './commerce'` in the root `index.ts`). If any is missing, the entire package will fail to load with a `Cannot find module` error.
+
+### Installing peer dependencies
+
+Install the toolkit and all required peer dependencies in one command:
+
+```bash
+npm install @adobe-commerce/aio-toolkit \
+  @adobe/aio-sdk \
+  @adobe/aio-lib-ims \
+  @adobe/aio-lib-telemetry \
+  @opentelemetry/resources \
+  graphql
+```
+
+Or individually if you prefer to control versions:
+
+```bash
+npm install @adobe-commerce/aio-toolkit
+
+# Required peer dependencies
+npm install @adobe/aio-sdk@^5.0.0
+npm install @adobe/aio-lib-ims@^7.0.0
+npm install @adobe/aio-lib-telemetry@^1.0.0
+npm install @opentelemetry/resources@^2.0.0
+npm install graphql@^16.0.0
+```
+
+> **Note for App Builder projects:** `@adobe/aio-sdk`, `graphql`, and `@adobe/aio-lib-ims` are almost always already present in a standard App Builder project. Run `npm list @adobe/aio-sdk graphql @adobe/aio-lib-ims` to check before installing.
+
+### Resolving `ERESOLVE` errors
+
+If you see an `ERESOLVE` error when installing, it means one of the required peer dependencies is installed in your project at a version outside the supported range.
+
+**Check which peer dep is conflicting:**
+
+```bash
+npm install @adobe-commerce/aio-toolkit 2>&1 | grep "Found:"
+```
+
+**Upgrade the conflicting package to a compatible version:**
+
+```bash
+# @adobe/aio-sdk must be >=5.0.0
+npm install @adobe/aio-sdk@latest
+
+# graphql must be >=14.0.0
+npm install graphql@latest
+
+# @adobe/aio-lib-ims must be >=7.0.0
+npm install @adobe/aio-lib-ims@latest
+
+# @adobe/aio-lib-telemetry must be >=1.0.0
+npm install @adobe/aio-lib-telemetry@latest
+
+# @opentelemetry/resources must be >=2.0.0
+npm install @opentelemetry/resources@latest
+```
+
+If upgrading is not immediately possible, you can bypass the check with `--legacy-peer-deps` (not recommended for production):
+
+```bash
+npm install @adobe-commerce/aio-toolkit --legacy-peer-deps
+```
+
 ## License
 
 See the LICENSE file (in package) for license rights and limitations.

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 import openwhisk, { Dict, Activation } from 'openwhisk';
+import { DbCollection, DbClient } from '@adobe/aio-lib-db';
 import { EntrypointInstrumentationConfig } from '@adobe/aio-lib-telemetry';
 import { LogRecordProcessor } from '@opentelemetry/sdk-logs';
 import { SdkLogRecord } from '@adobe/aio-lib-telemetry/otel';
@@ -327,6 +328,67 @@ declare class RuntimeApiGatewayService {
     delete(endpoint: string, additionalHeaders?: Record<string, string>): Promise<any>;
 }
 
+declare enum AbdbColumnType {
+    STRING = "STRING",
+    NUMBER = "NUMBER",
+    BOOLEAN = "BOOLEAN",
+    DATETIME = "DATETIME"
+}
+interface AbdbColumnOptions {
+    name: string;
+    type: AbdbColumnType;
+    description?: string;
+    isRequired?: boolean;
+}
+interface AbdbColumnJson {
+    name: string;
+    type: AbdbColumnType;
+    description?: string;
+    isRequired?: true;
+}
+
+declare class AbdbColumn {
+    private readonly _name;
+    private readonly _type;
+    private readonly _description;
+    private readonly _isRequired;
+    constructor(options: AbdbColumnOptions);
+    getName(): string;
+    getType(): AbdbColumnType;
+    getDescription(): string | undefined;
+    getIsRequired(): boolean;
+    toJSON(): AbdbColumnJson;
+    clone(overrides?: Partial<AbdbColumnOptions>): AbdbColumn;
+    validate(value: unknown): void;
+    private _isMissingValue;
+    private _validateStringValue;
+    private _validateNumberValue;
+    private _validateBooleanValue;
+    private _validateDateTimeValue;
+}
+
+type AddColumnOptions = Omit<AbdbColumnOptions, 'name' | 'type'>;
+type AbdbRunCallback<T = unknown> = (collection: DbCollection, client: DbClient) => Promise<T>;
+
+type AbdbCollectionCallback = (collection: AbdbCollection) => void;
+declare class AbdbCollection {
+    private readonly _name;
+    private readonly _columns;
+    constructor(name: string, callback?: AbdbCollectionCallback);
+    getName(): string;
+    addColumn(name: string, type: AbdbColumnType, options?: AddColumnOptions): this;
+    addColumn(name: string, type: AbdbColumnType, description?: string, isRequired?: boolean): this;
+    getColumns(): AbdbColumn[];
+    getColumn(name: string): AbdbColumn | undefined;
+    hasColumn(name: string): boolean;
+    validate(record: Record<string, unknown>): void;
+    validateAll(record: Record<string, unknown>): string[];
+    run<T>(callback: AbdbRunCallback<T>, token: string, region?: string): Promise<T>;
+    private _validateCollectionName;
+    private _validateColumnName;
+    private _validateIdentifier;
+}
+
 declare class TelemetryInputError extends Error {
     constructor(message: string);
 }
@@ -989,4 +1051,4 @@ declare class AdminUiSdk {
     getRegistration(): AdminUiSdkRegistration;
 }
 
-export { AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, type BaseTelemetry, type BaseTelemetryValidator, BasicAuthConnection, BearerToken, type BearerTokenInfo, type CommerceEvent, type CommerceEventConfig, type CommerceEventField, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileMetadata, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, ImsToken, type ImsTokenResult, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, JsonMessageProcessor, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardCommerce, type OnboardCommerceConfig, type OnboardCommerceResult, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, OnboardEvents as OnboardIOEvents, Openwhisk, OpenwhiskAction, type OpenwhiskConfig, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, RuntimeApiGatewayService, ShippingCarrier, type ShippingCarrierData, ShippingCarrierMethod, type ShippingCarrierMethodAdditionalData, type ShippingCarrierMethodData, ShippingCarrierResponse, SignatureVerification, SuccessChecker, type SuccessResponse, Telemetry, TelemetryInputError, type TokenResult, Validator, WebhookAction, type WebhookActionAddResponse, type WebhookActionExceptionResponse, WebhookActionOperation, type WebhookActionRemoveResponse, type WebhookActionReplaceResponse, WebhookActionResponse, type WebhookActionResponseType, type WebhookActionSuccessResponse, type WorkspaceConfig };
+export { AbdbCollection, type AbdbCollectionCallback, AbdbColumn, type AbdbColumnJson, type AbdbColumnOptions, AbdbColumnType, type AbdbRunCallback, type AddColumnOptions, AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, type BaseTelemetry, type BaseTelemetryValidator, BasicAuthConnection, BearerToken, type BearerTokenInfo, type CommerceEvent, type CommerceEventConfig, type CommerceEventField, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileMetadata, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, ImsToken, type ImsTokenResult, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, JsonMessageProcessor, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardCommerce, type OnboardCommerceConfig, type OnboardCommerceResult, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, OnboardEvents as OnboardIOEvents, Openwhisk, OpenwhiskAction, type OpenwhiskConfig, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, RuntimeApiGatewayService, ShippingCarrier, type ShippingCarrierData, ShippingCarrierMethod, type ShippingCarrierMethodAdditionalData, type ShippingCarrierMethodData, ShippingCarrierResponse, SignatureVerification, SuccessChecker, type SuccessResponse, Telemetry, TelemetryInputError, type TokenResult, Validator, WebhookAction, type WebhookActionAddResponse, type WebhookActionExceptionResponse, WebhookActionOperation, type WebhookActionRemoveResponse, type WebhookActionReplaceResponse, WebhookActionResponse, type WebhookActionResponseType, type WebhookActionSuccessResponse, type WorkspaceConfig };

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import openwhisk, { Dict, Activation } from 'openwhisk';
+import { DbCollection, DbClient } from '@adobe/aio-lib-db';
 import { EntrypointInstrumentationConfig } from '@adobe/aio-lib-telemetry';
 import { LogRecordProcessor } from '@opentelemetry/sdk-logs';
 import { SdkLogRecord } from '@adobe/aio-lib-telemetry/otel';
@@ -327,6 +328,67 @@ declare class RuntimeApiGatewayService {
     delete(endpoint: string, additionalHeaders?: Record<string, string>): Promise<any>;
 }
 
+declare enum AbdbColumnType {
+    STRING = "STRING",
+    NUMBER = "NUMBER",
+    BOOLEAN = "BOOLEAN",
+    DATETIME = "DATETIME"
+}
+interface AbdbColumnOptions {
+    name: string;
+    type: AbdbColumnType;
+    description?: string;
+    isRequired?: boolean;
+}
+interface AbdbColumnJson {
+    name: string;
+    type: AbdbColumnType;
+    description?: string;
+    isRequired?: true;
+}
+
+declare class AbdbColumn {
+    private readonly _name;
+    private readonly _type;
+    private readonly _description;
+    private readonly _isRequired;
+    constructor(options: AbdbColumnOptions);
+    getName(): string;
+    getType(): AbdbColumnType;
+    getDescription(): string | undefined;
+    getIsRequired(): boolean;
+    toJSON(): AbdbColumnJson;
+    clone(overrides?: Partial<AbdbColumnOptions>): AbdbColumn;
+    validate(value: unknown): void;
+    private _isMissingValue;
+    private _validateStringValue;
+    private _validateNumberValue;
+    private _validateBooleanValue;
+    private _validateDateTimeValue;
+}
+
+type AddColumnOptions = Omit<AbdbColumnOptions, 'name' | 'type'>;
+type AbdbRunCallback<T = unknown> = (collection: DbCollection, client: DbClient) => Promise<T>;
+
+type AbdbCollectionCallback = (collection: AbdbCollection) => void;
+declare class AbdbCollection {
+    private readonly _name;
+    private readonly _columns;
+    constructor(name: string, callback?: AbdbCollectionCallback);
+    getName(): string;
+    addColumn(name: string, type: AbdbColumnType, options?: AddColumnOptions): this;
+    addColumn(name: string, type: AbdbColumnType, description?: string, isRequired?: boolean): this;
+    getColumns(): AbdbColumn[];
+    getColumn(name: string): AbdbColumn | undefined;
+    hasColumn(name: string): boolean;
+    validate(record: Record<string, unknown>): void;
+    validateAll(record: Record<string, unknown>): string[];
+    run<T>(callback: AbdbRunCallback<T>, token: string, region?: string): Promise<T>;
+    private _validateCollectionName;
+    private _validateColumnName;
+    private _validateIdentifier;
+}
+
 declare class TelemetryInputError extends Error {
     constructor(message: string);
 }
@@ -989,4 +1051,4 @@ declare class AdminUiSdk {
     getRegistration(): AdminUiSdkRegistration;
 }
 
-export { AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, type BaseTelemetry, type BaseTelemetryValidator, BasicAuthConnection, BearerToken, type BearerTokenInfo, type CommerceEvent, type CommerceEventConfig, type CommerceEventField, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileMetadata, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, ImsToken, type ImsTokenResult, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, JsonMessageProcessor, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardCommerce, type OnboardCommerceConfig, type OnboardCommerceResult, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, OnboardEvents as OnboardIOEvents, Openwhisk, OpenwhiskAction, type OpenwhiskConfig, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, RuntimeApiGatewayService, ShippingCarrier, type ShippingCarrierData, ShippingCarrierMethod, type ShippingCarrierMethodAdditionalData, type ShippingCarrierMethodData, ShippingCarrierResponse, SignatureVerification, SuccessChecker, type SuccessResponse, Telemetry, TelemetryInputError, type TokenResult, Validator, WebhookAction, type WebhookActionAddResponse, type WebhookActionExceptionResponse, WebhookActionOperation, type WebhookActionRemoveResponse, type WebhookActionReplaceResponse, WebhookActionResponse, type WebhookActionResponseType, type WebhookActionSuccessResponse, type WorkspaceConfig };
+export { AbdbCollection, type AbdbCollectionCallback, AbdbColumn, type AbdbColumnJson, type AbdbColumnOptions, AbdbColumnType, type AbdbRunCallback, type AddColumnOptions, AdminUiSdk, type AdminUiSdkRegistration, AdobeAuth, AdobeCommerceClient, type AdobeIMSConfig, type BaseTelemetry, type BaseTelemetryValidator, BasicAuthConnection, BearerToken, type BearerTokenInfo, type CommerceEvent, type CommerceEventConfig, type CommerceEventField, type Connection, type CreateEventResult, CreateEvents, type CreateProviderParams, type CreateProviderResult, type CreateRegistrationResult, CreateRegistrations, type ErrorResponse, EventConsumerAction, type EventData, type EventMetadata, type EventMetadataInputModel, type EventMetadataListResponse, EventMetadataManager, type ExtendedRequestError, type FileMetadata, type FileRecord, FileRepository, GenerateBasicAuthToken, type GetProviderQueryParams, type GetRegistrationQueryParams, GraphQlAction, type HALLink, type Headers, HttpMethod, HttpStatus, IOEventsApiError, type IOEventsError, ImsConnection, ImsToken, type ImsTokenResult, InfiniteLoopBreaker, type InfiniteLoopData, IoEventsGlobals, JsonMessageProcessor, type ListProvidersQueryParams, type ListRegistrationQueryParams, type MenuItem, Oauth1aConnection, OnboardCommerce, type OnboardCommerceConfig, type OnboardCommerceResult, OnboardEvents, type OnboardEventsInput, type OnboardEventsResponse, OnboardEvents as OnboardIOEvents, Openwhisk, OpenwhiskAction, type OpenwhiskConfig, type Page, Parameters, type Provider, type ProviderInputModel, ProviderManager, PublishEvent, type PublishEventResult, type Registration, type RegistrationCreateModel, type RegistrationListResponse, RegistrationManager, RestClient, RuntimeAction, RuntimeActionResponse, type RuntimeActionResponseType, RuntimeApiGatewayService, ShippingCarrier, type ShippingCarrierData, ShippingCarrierMethod, type ShippingCarrierMethodAdditionalData, type ShippingCarrierMethodData, ShippingCarrierResponse, SignatureVerification, SuccessChecker, type SuccessResponse, Telemetry, TelemetryInputError, type TokenResult, Validator, WebhookAction, type WebhookActionAddResponse, type WebhookActionExceptionResponse, WebhookActionOperation, type WebhookActionRemoveResponse, type WebhookActionReplaceResponse, WebhookActionResponse, type WebhookActionResponseType, type WebhookActionSuccessResponse, type WorkspaceConfig };