@adobe-commerce/aio-toolkit 1.1.1 → 1.2.0

package/dist/index.mjs

@@ -3667,6 +3667,440 @@ __name(_RuntimeApiGatewayService, "RuntimeApiGatewayService");
 _RuntimeApiGatewayService.BASE_URL = "https://adobeioruntime.net/apis";
 var RuntimeApiGatewayService = _RuntimeApiGatewayService;
 
+// src/framework/abdb/column/types.ts
+var AbdbColumnType = /* @__PURE__ */ ((AbdbColumnType2) => {
+  AbdbColumnType2["STRING"] = "STRING";
+  AbdbColumnType2["NUMBER"] = "NUMBER";
+  AbdbColumnType2["BOOLEAN"] = "BOOLEAN";
+  AbdbColumnType2["DATETIME"] = "DATETIME";
+  return AbdbColumnType2;
+})(AbdbColumnType || {});
+
+// src/framework/abdb/column/index.ts
+var ISO_8601_DATETIME = /^\d{4}-\d{2}-\d{2}([Tt ]\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?(Z|[+-]\d{2}(:?\d{2})?)?)?$/;
+var _AbdbColumn = class _AbdbColumn {
+  /**
+   * @param options - Field definition
+   * @throws {Error} When `name` is missing or blank, or `type` is missing / not a member of {@link AbdbColumnType}
+   */
+  constructor(options) {
+    if (!options?.name?.trim()) {
+      throw new Error('AbdbColumn: "name" is required and cannot be empty');
+    }
+    if (!options.type || !Object.values(AbdbColumnType).includes(options.type)) {
+      throw new Error('AbdbColumn: "type" is required');
+    }
+    this._name = options.name.trim();
+    this._type = options.type;
+    this._description = void 0;
+    this._isRequired = options.isRequired ?? false;
+    if (options.description !== void 0) {
+      const trimmed = options.description.trim();
+      if (trimmed.length > 0) {
+        this._description = trimmed;
+      }
+    }
+    Object.freeze(this);
+  }
+  /**
+   * Returns the trimmed field name.
+   */
+  getName() {
+    return this._name;
+  }
+  /**
+   * Returns the expected value type for this column.
+   */
+  getType() {
+    return this._type;
+  }
+  /**
+   * Returns the optional description, if one was provided and non-whitespace.
+   *
+   * @returns Description string, or `undefined` when not set
+   */
+  getDescription() {
+    return this._description;
+  }
+  /**
+   * Returns whether a value is mandatory for {@link AbdbColumn#validate}.
+   *
+   * @returns `true` if constructed with `isRequired: true`; otherwise `false`
+   */
+  getIsRequired() {
+    return this._isRequired;
+  }
+  /**
+   * Serializes this column to a plain object for JSON (config files, APIs, persistence).
+   */
+  toJSON() {
+    const json = {
+      name: this._name,
+      type: this._type
+    };
+    if (this._description !== void 0) {
+      json.description = this._description;
+    }
+    if (this._isRequired) {
+      json.isRequired = true;
+    }
+    return json;
+  }
+  /**
+   * Creates a new column with the same or overridden options. Does not mutate this instance.
+   *
+   * Passing `description: '   '` (blank / whitespace) clears the description on the new column.
+   *
+   * @param overrides - Partial options; omitted keys keep current values
+   * @returns A new {@link AbdbColumn} instance
+   */
+  clone(overrides = {}) {
+    const name = overrides.name ?? this._name;
+    const type = overrides.type ?? this._type;
+    const isRequired = overrides.isRequired ?? this._isRequired;
+    if (overrides.description !== void 0) {
+      return new _AbdbColumn({ name, type, description: overrides.description, isRequired });
+    }
+    if (this._description !== void 0) {
+      return new _AbdbColumn({ name, type, description: this._description, isRequired });
+    }
+    return new _AbdbColumn({ name, type, isRequired });
+  }
+  /**
+   * Validates a payload value against this column's requiredness and {@link AbdbColumnType}.
+   *
+   * **Missing values** (`undefined`, `null`, or empty / whitespace-only strings) are handled first:
+   * if `isRequired` is `false`, validation succeeds; if `true`, throws.
+   *
+   * **Type rules** (when a non-missing value is present):
+   * - `STRING`: primitive string
+   * - `NUMBER`: finite number, or a non-empty string whose trim parses to a finite number via `Number`
+   * - `BOOLEAN`: primitive boolean, or non-empty trimmed string `"true"` / `"false"` (case-insensitive)
+   * - `DATETIME`: valid `Date`, finite numeric timestamp (ms), or non-empty trimmed ISO 8601 date/datetime string
+   *
+   * @param value - Document field or API payload value
+   * @throws {Error} When required and missing, or when the value does not match the column type
+   */
+  validate(value) {
+    if (this._isMissingValue(value)) {
+      if (this._isRequired) {
+        throw new Error(`AbdbColumn: "${this._name}" is required`);
+      }
+      return;
+    }
+    switch (this._type) {
+      case "STRING" /* STRING */:
+        this._validateStringValue(value);
+        return;
+      case "NUMBER" /* NUMBER */:
+        this._validateNumberValue(value);
+        return;
+      case "BOOLEAN" /* BOOLEAN */:
+        this._validateBooleanValue(value);
+        return;
+      case "DATETIME" /* DATETIME */:
+        this._validateDateTimeValue(value);
+        return;
+      default: {
+        const _unreachable = this._type;
+        throw new Error(`AbdbColumn: unhandled type "${_unreachable}"`);
+      }
+    }
+  }
+  /**
+   * Whether `value` counts as absent for requiredness checks (before type validation).
+   *
+   * @returns `true` for `undefined`, `null`, or a string that is empty after trim
+   */
+  _isMissingValue(value) {
+    if (value === void 0 || value === null) {
+      return true;
+    }
+    return typeof value === "string" && value.trim() === "";
+  }
+  /**
+   * @throws {Error} When `value` is not a primitive string
+   */
+  _validateStringValue(value) {
+    if (typeof value !== "string") {
+      throw new Error(`AbdbColumn: "${this._name}" expects string, got ${typeof value}`);
+    }
+  }
+  /**
+   * @throws {Error} When not a finite number or numeric string
+   */
+  _validateNumberValue(value) {
+    if (typeof value === "number") {
+      if (Number.isFinite(value)) {
+        return;
+      }
+      throw new Error(`AbdbColumn: "${this._name}" expects a finite number, got ${String(value)}`);
+    }
+    if (typeof value === "string") {
+      const trimmed = value.trim();
+      const n = Number(trimmed);
+      if (Number.isFinite(n)) {
+        return;
+      }
+      throw new Error(
+        `AbdbColumn: "${this._name}" expects a finite number or numeric string, got ${JSON.stringify(value)}`
+      );
+    }
+    throw new Error(
+      `AbdbColumn: "${this._name}" expects a finite number or numeric string, got ${typeof value}`
+    );
+  }
+  /**
+   * @throws {Error} When not a boolean or `"true"` / `"false"` string
+   */
+  _validateBooleanValue(value) {
+    if (typeof value === "boolean") {
+      return;
+    }
+    if (typeof value === "string") {
+      const t = value.trim().toLowerCase();
+      if (t === "true" || t === "false") {
+        return;
+      }
+      throw new Error(
+        `AbdbColumn: "${this._name}" expects boolean or "true"/"false" string, got ${JSON.stringify(value)}`
+      );
+    }
+    throw new Error(
+      `AbdbColumn: "${this._name}" expects boolean or "true"/"false" string, got ${typeof value}`
+    );
+  }
+  /**
+   * @throws {Error} When not a valid `Date`, finite timestamp, or ISO 8601 string
+   */
+  _validateDateTimeValue(value) {
+    if (value instanceof Date) {
+      if (!Number.isNaN(value.getTime())) {
+        return;
+      }
+      throw new Error(`AbdbColumn: "${this._name}" expects a valid Date`);
+    }
+    if (typeof value === "number") {
+      if (Number.isFinite(value)) {
+        return;
+      }
+      throw new Error(
+        `AbdbColumn: "${this._name}" expects a finite numeric timestamp, got ${value}`
+      );
+    }
+    if (typeof value === "string") {
+      const s = value.trim();
+      if (!ISO_8601_DATETIME.test(s)) {
+        throw new Error(
+          `AbdbColumn: "${this._name}" expects ISO 8601 datetime string, got ${JSON.stringify(value)}`
+        );
+      }
+      const t = Date.parse(s);
+      if (Number.isNaN(t)) {
+        throw new Error(
+          `AbdbColumn: "${this._name}" expects ISO 8601 datetime string, got ${JSON.stringify(value)}`
+        );
+      }
+      return;
+    }
+    throw new Error(
+      `AbdbColumn: "${this._name}" expects Date, finite numeric timestamp, or ISO 8601 datetime string, got ${typeof value}`
+    );
+  }
+};
+__name(_AbdbColumn, "AbdbColumn");
+var AbdbColumn = _AbdbColumn;
+var column_default = AbdbColumn;
+
+// src/framework/abdb/collection/index.ts
+import { init as initDb, DbError } from "@adobe/aio-lib-db";
+var _AbdbCollection = class _AbdbCollection {
+  /**
+   * Creates a collection and optionally configures it in a callback (e.g. chained {@link addColumn} calls).
+   *
+   * @param name - Raw collection name; trimmed and validated
+   * @param callback - Optional function invoked with `this` for fluent setup
+   * @throws {Error} When `name` is empty, whitespace-only, or contains invalid characters
+   */
+  constructor(name, callback) {
+    this._name = this._validateCollectionName(name);
+    this._columns = /* @__PURE__ */ new Map();
+    if (callback) {
+      callback(this);
+    }
+  }
+  /**
+   * Returns this collection's name.
+   */
+  getName() {
+    return this._name;
+  }
+  addColumn(name, type, descriptionOrOptions, isRequired) {
+    const trimmed = this._validateColumnName(name);
+    if (this._columns.has(trimmed)) {
+      throw new Error(`AbdbCollection: duplicate column name "${trimmed}"`);
+    }
+    const columnOptions = { name: trimmed, type };
+    if (typeof descriptionOrOptions === "string") {
+      columnOptions.description = descriptionOrOptions;
+      if (isRequired !== void 0) {
+        columnOptions.isRequired = isRequired;
+      }
+    } else if (descriptionOrOptions !== void 0) {
+      if (descriptionOrOptions.description !== void 0) {
+        columnOptions.description = descriptionOrOptions.description;
+      }
+      if (descriptionOrOptions.isRequired !== void 0) {
+        columnOptions.isRequired = descriptionOrOptions.isRequired;
+      }
+    }
+    this._columns.set(trimmed, new column_default(columnOptions));
+    return this;
+  }
+  /**
+   * Returns a defensive copy of columns in insertion order.
+   */
+  getColumns() {
+    return Array.from(this._columns.values());
+  }
+  /**
+   * Returns the column registered under `name`, or `undefined` if no such column exists.
+   *
+   * @param name - Column name to look up (exact match after trimming)
+   * @returns The {@link AbdbColumn} instance, or `undefined`
+   */
+  getColumn(name) {
+    return this._columns.get(name.trim());
+  }
+  /**
+   * Returns `true` when a column with the given name has been registered.
+   *
+   * @param name - Column name to check (exact match after trimming)
+   */
+  hasColumn(name) {
+    return this._columns.has(name.trim());
+  }
+  /**
+   * Validates a document-style object against this collection's columns. Throws on the **first** failing
+   * column. Use {@link validateAll} when you need all errors reported at once.
+   *
+   * Missing keys are read as `undefined`, so a **required** column whose key is absent fails validation.
+   * Extra keys not matching any column name are ignored.
+   *
+   * @param record - Key/value payload whose keys are column names
+   * @throws {Error} When any column validation fails (requiredness or type)
+   */
+  validate(record) {
+    for (const col of this._columns.values()) {
+      col.validate(record[col.getName()]);
+    }
+  }
+  /**
+   * Validates a document-style object against **all** columns and collects every error instead of
+   * stopping at the first failure. Useful at API boundaries where reporting all problems at once
+   * gives a better developer or end-user experience.
+   *
+   * Returns an empty array when the record is fully valid.
+   *
+   * @param record - Key/value payload whose keys are column names
+   * @returns Array of validation error messages, one per failing column (insertion order)
+   *
+   * @example
+   * ```typescript
+   * const errors = orders.validateAll(payload);
+   * if (errors.length > 0) {
+   *   return { status: 400, body: { errors } };
+   * }
+   * ```
+   */
+  validateAll(record) {
+    const errors = [];
+    for (const col of this._columns.values()) {
+      try {
+        col.validate(record[col.getName()]);
+      } catch (e) {
+        errors.push(e instanceof Error ? e.message : String(e));
+      }
+    }
+    return errors;
+  }
+  /**
+   * Connects to the database (via `@adobe/aio-lib-db`), runs `callback` with the selected DB **collection**
+   * handle and the **client**, then closes the client in a `finally` block.
+   *
+   * **Errors:** `DbError` instances are rethrown as `AbdbCollection: database error: …`;
+   * any other value is wrapped as `AbdbCollection: unexpected error: …`.
+   *
+   * @param callback - Receives `(collection, client)` after connect
+   * @param token - IMS access token for `initDb`
+   * @param region - Data region (default: `'amer'`)
+   * @returns Promise resolving to the callback's return value
+   * @throws {Error} On init, connect, `DbError`, or callback failure
+   */
+  async run(callback, token, region = "amer") {
+    let client;
+    try {
+      const db = await initDb({ token, region });
+      client = await db.connect();
+      const collection = await client.collection(this._name);
+      return await callback(collection, client);
+    } catch (error) {
+      if (error instanceof DbError) {
+        throw new Error(`AbdbCollection: database error: ${error.message}`);
+      }
+      const detail = error instanceof Error ? error.message : String(error);
+      throw new Error(`AbdbCollection: unexpected error: ${detail}`);
+    } finally {
+      await client?.close();
+    }
+  }
+  /**
+   * Validates and normalizes the collection identifier used at construction.
+   *
+   * @throws {Error} If the name is empty or not `[a-zA-Z0-9_]`
+   */
+  _validateCollectionName(name) {
+    return this._validateIdentifier(
+      name,
+      'AbdbCollection: "name" is required and cannot be empty',
+      "AbdbCollection: name must contain only alphanumeric characters and underscores"
+    );
+  }
+  /**
+   * Validates and normalizes a column name before {@link addColumn} stores it.
+   *
+   * @throws {Error} If the name is empty or not `[a-zA-Z0-9_]`
+   */
+  _validateColumnName(name) {
+    return this._validateIdentifier(
+      name,
+      'AbdbCollection: column "name" is required and cannot be empty',
+      "AbdbCollection: column name must contain only alphanumeric characters and underscores"
+    );
+  }
+  /**
+   * Shared validation for collection and column identifiers.
+   *
+   * @param raw - Unvalidated string
+   * @param emptyMessage - Thrown when `raw` is missing or whitespace-only
+   * @param invalidMessage - Thrown when the trimmed value is not alphanumeric with underscores
+   * @returns The trimmed identifier
+   */
+  _validateIdentifier(raw, emptyMessage, invalidMessage) {
+    if (!raw || raw.trim() === "") {
+      throw new Error(emptyMessage);
+    }
+    const trimmed = raw.trim();
+    if (!/^[a-zA-Z0-9_]+$/.test(trimmed)) {
+      throw new Error(invalidMessage);
+    }
+    return trimmed;
+  }
+};
+__name(_AbdbCollection, "AbdbCollection");
+var AbdbCollection = _AbdbCollection;
+var collection_default = AbdbCollection;
+
 // src/integration/onboard-events/index.ts
 import { Core as Core2 } from "@adobe/aio-sdk";
 
@@ -8792,6 +9226,9 @@ var _AdminUiSdk = class _AdminUiSdk {
 __name(_AdminUiSdk, "AdminUiSdk");
 var AdminUiSdk = _AdminUiSdk;
 export {
+  collection_default as AbdbCollection,
+  column_default as AbdbColumn,
+  AbdbColumnType,
   AdminUiSdk,
   adobe_auth_default as AdobeAuth,
   adobe_commerce_client_default as AdobeCommerceClient,