@adobe-commerce/aio-toolkit 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -5,6 +5,51 @@ 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

package/README.md

@@ -675,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**

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 };