@adobe-commerce/aio-toolkit 1.1.1 → 1.2.1

package/dist/index.js

@@ -31,6 +31,10 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/index.ts
 var index_exports = {};
 __export(index_exports, {
+  AbdbCollection: () => collection_default,
+  AbdbColumn: () => column_default,
+  AbdbColumnType: () => AbdbColumnType,
+  AbdbRepository: () => abdb_repository_default,
   AdminUiSdk: () => AdminUiSdk,
   AdobeAuth: () => adobe_auth_default,
   AdobeCommerceClient: () => adobe_commerce_client_default,
@@ -2391,6 +2395,674 @@ __name(_FileRepository, "FileRepository");
 var FileRepository = _FileRepository;
 var file_repository_default = FileRepository;
 
+// src/framework/abdb/collection/index.ts
+var import_aio_lib_db = require("@adobe/aio-lib-db");
+
+// 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
+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 (0, import_aio_lib_db.init)({ token, region });
+      client = await db.connect();
+      const collection = await client.collection(this._name);
+      return await callback(collection, client);
+    } catch (error) {
+      if (error instanceof import_aio_lib_db.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/framework/repository/abdb-repository/index.ts
+var _AbdbRepository = class _AbdbRepository {
+  /**
+   * @param collection - Schema and DB-connection wrapper for the target collection
+   * @param token - IMS access token forwarded to every `collection.run()` call
+   * @param region - Data region forwarded to every `collection.run()` call (default: `'amer'`)
+   * @throws {Error} When `collection` is not an {@link AbdbCollection} instance, or `token` is missing
+   */
+  constructor(collection, token, region = "amer") {
+    if (!(collection instanceof collection_default)) {
+      throw new Error('AbdbRepository: "collection" must be an AbdbCollection instance');
+    }
+    if (!token || typeof token !== "string" || !token.trim()) {
+      throw new Error('AbdbRepository: "token" is required');
+    }
+    if (!collection.hasColumn("_created_at")) {
+      collection.addColumn("_created_at", "DATETIME" /* DATETIME */, "Record creation timestamp");
+    }
+    if (!collection.hasColumn("_updated_at")) {
+      collection.addColumn("_updated_at", "DATETIME" /* DATETIME */, "Record last-updated timestamp");
+    }
+    this._collection = collection;
+    this._token = token;
+    this._region = region;
+  }
+  /**
+   * Returns the name of the underlying collection.
+   */
+  getName() {
+    return this._collection.getName();
+  }
+  /**
+   * Returns the underlying {@link AbdbCollection} instance.
+   */
+  getCollection() {
+    return this._collection;
+  }
+  /**
+   * Returns all documents matching `filter` as an array.
+   * Passing no filter (or an empty object) returns every document in the collection.
+   *
+   * @param filter - Optional query filter (default: `{}`)
+   * @returns Array of matched documents (may be empty)
+   */
+  async find(filter = {}) {
+    return this._collection.run(
+      async (collection) => {
+        return collection.find(filter).toArray();
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Returns the first document matching `filter`, or `null` if none found.
+   *
+   * @param filter - Query filter (e.g. `{ _id: 'abc' }` or `{ email: 'a@b.com' }`)
+   * @returns The matched document, or `null`
+   */
+  async findOne(filter) {
+    return this._collection.run(
+      async (collection) => {
+        return collection.findOne(filter);
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Returns `true` when a document with the given `_id` exists in the collection.
+   * Uses `countDocuments` rather than fetching the full document for efficiency.
+   *
+   * @param id - The `_id` to check
+   * @returns `true` if the document exists, `false` otherwise
+   */
+  async exists(id) {
+    if (!id) return false;
+    const n = await this._collection.run(
+      (collection) => {
+        return collection.countDocuments({ _id: id });
+      },
+      this._token,
+      this._region
+    );
+    return n > 0;
+  }
+  /**
+   * Returns the number of documents in the collection matching `filter`.
+   * Passing no filter (or an empty object) counts every document.
+   *
+   * @param filter - Optional query filter (default: `{}`)
+   * @returns Total number of matching documents
+   */
+  async count(filter = {}) {
+    return this._collection.run(
+      (collection) => {
+        return collection.countDocuments(filter);
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Inserts or updates a document.
+   *
+   * - **Insert** (no `id`): stamps both `_created_at` and `_updated_at`, runs full schema
+   *   validation, then calls `insertOne`. Returns the new document's `_id`.
+   * - **Update** (with `id`): stamps `_updated_at`, runs **partial** validation (only columns
+   *   present in the payload are checked — required fields that are absent are not enforced
+   *   because they already exist in the stored document), then calls `updateOne` with
+   *   `upsert: true`. Returns the same `id` that was passed in.
+   *
+   * @param payload - Document fields to write
+   * @param id - When provided, updates the document with this `_id`; otherwise inserts
+   * @returns The `_id` of the inserted or updated document
+   */
+  async save(payload = {}, id = "") {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    if (id) {
+      const updatePayload = { ...payload, _updated_at: now };
+      this._validatePartial(updatePayload);
+      await this._collection.run(
+        async (collection) => {
+          await collection.updateOne({ _id: id }, updatePayload, { upsert: true });
+        },
+        this._token,
+        this._region
+      );
+      return id;
+    }
+    const insertPayload = { ...payload, _created_at: now, _updated_at: now };
+    this._collection.validate(insertPayload);
+    return this._collection.run(
+      async (collection) => {
+        return collection.insertOne(insertPayload);
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Deletes the document with the given `_id`. No-ops silently when `id` is empty.
+   *
+   * @param id - The `_id` of the document to delete
+   */
+  async delete(id = "") {
+    if (!id) return;
+    await this._collection.run(
+      async (collection) => {
+        await collection.deleteOne({ _id: id });
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Inserts multiple documents in a single `insertMany` call.
+   * Each payload is stamped with `_created_at` / `_updated_at` and validated
+   * against the full collection schema before the bulk write is sent to the DB.
+   *
+   * @param payloads - Array of document payloads to insert
+   * @returns Array of inserted `_id` values in insertion order
+   */
+  async insertAll(payloads) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const insertPayloads = payloads.map((payload) => {
+      const doc = { ...payload, _created_at: now, _updated_at: now };
+      this._collection.validate(doc);
+      return doc;
+    });
+    return this._collection.run(
+      async (collection) => {
+        return collection.insertMany(insertPayloads);
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Applies a partial update to all documents matching `filter` using a single `updateMany` call.
+   * Stamps `_updated_at` on every matched document and runs partial validation on the payload
+   * (only the columns present in the payload are checked).
+   *
+   * @param payload - Fields to update on every matched document
+   * @param filter - Query condition selecting which documents to update (default: `{}` — all documents)
+   */
+  async updateAll(payload, filter = {}) {
+    const updatePayload = { ...payload, _updated_at: (/* @__PURE__ */ new Date()).toISOString() };
+    this._validatePartial(updatePayload);
+    await this._collection.run(
+      async (collection) => {
+        await collection.updateMany(filter, updatePayload);
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Deletes all documents matching `filter` using a single `deleteMany` call.
+   * Passing no filter (or an empty object) deletes every document in the collection.
+   *
+   * @param filter - Optional query filter (default: `{}`)
+   */
+  async deleteAll(filter = {}) {
+    await this._collection.run(
+      async (collection) => {
+        await collection.deleteMany(filter);
+      },
+      this._token,
+      this._region
+    );
+  }
+  /**
+   * Validates only the columns whose keys are present in `record`.
+   * Required columns that are absent from the payload are intentionally skipped —
+   * they already exist in the stored document and are not being changed.
+   *
+   * Used by the update path of {@link save} and {@link updateAll}.
+   */
+  _validatePartial(record) {
+    for (const col of this._collection.getColumns()) {
+      const key = col.getName();
+      if (key in record) {
+        col.validate(record[key]);
+      }
+    }
+  }
+};
+__name(_AbdbRepository, "AbdbRepository");
+var AbdbRepository = _AbdbRepository;
+var abdb_repository_default = AbdbRepository;
+
 // src/framework/publish-event/index.ts
 var import_aio_sdk3 = require("@adobe/aio-sdk");
 var import_cloudevents = require("cloudevents");
@@ -8852,6 +9524,10 @@ __name(_AdminUiSdk, "AdminUiSdk");
 var AdminUiSdk = _AdminUiSdk;
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  AbdbCollection,
+  AbdbColumn,
+  AbdbColumnType,
+  AbdbRepository,
   AdminUiSdk,
   AdobeAuth,
   AdobeCommerceClient,