@adobe/spacecat-shared-data-access 2.16.1 → 2.17.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@adobe/spacecat-shared-data-access-v2.17.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.17.0...@adobe/spacecat-shared-data-access-v2.17.1) (2025-05-03)
+
+
+### Bug Fixes
+
+* **deps:** update external fixes ([#712](https://github.com/adobe/spacecat-shared/issues/712)) ([76cebd2](https://github.com/adobe/spacecat-shared/commit/76cebd2a7a7b9799e4ca265833620eada01f5c8c))
+
+# [@adobe/spacecat-shared-data-access-v2.17.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.16.1...@adobe/spacecat-shared-data-access-v2.17.0) (2025-04-28)
+
+
+### Features
+
+* async job ([#698](https://github.com/adobe/spacecat-shared/issues/698)) ([31cf58f](https://github.com/adobe/spacecat-shared/commit/31cf58fc9ef128d2cf094afe0286932c7edc369d))
+
 # [@adobe/spacecat-shared-data-access-v2.16.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v2.16.0...@adobe/spacecat-shared-data-access-v2.16.1) (2025-04-26)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "2.16.1",
+  "version": "2.17.1",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {
@@ -35,8 +35,8 @@
   },
   "dependencies": {
     "@adobe/spacecat-shared-utils": "1.33.1",
-    "@aws-sdk/client-dynamodb": "3.797.0",
-    "@aws-sdk/lib-dynamodb": "3.797.0",
+    "@aws-sdk/client-dynamodb": "3.799.0",
+    "@aws-sdk/lib-dynamodb": "3.799.0",
     "@types/joi": "17.2.3",
     "aws-xray-sdk": "3.10.3",
     "electrodb": "3.4.1",

package/src/models/async-job/README.md

@@ -0,0 +1,67 @@
+# AsyncJob Entity for Asynchronous HTTP APIs
+
+## Use Case
+
+The `AsyncJob` entity is designed to support asynchronous HTTP APIs, such as those commonly implemented on AWS with API Gateway and Lambda. In this pattern:
+
+- **Client submits a job** (e.g., a long-running computation or export) via an HTTP endpoint. The API returns HTTP 202 (Accepted) and a Job ID.
+- **Client polls for job status** using the Job ID.
+- **Client retrieves the result** when the job is completed, either inline or via a URL (e.g., S3).
+
+This pattern is ideal for workflows where immediate results are not possible, and the client must check back later for completion.
+
+## AsyncJob Schema Overview
+
+The `AsyncJob` entity persists the state and metadata of each asynchronous job. Key attributes include:
+
+- `asyncJobId`: Unique identifier (UUID v4) for the job.
+- `status`: Job lifecycle status (`IN_PROGRESS`, `COMPLETED`, `FAILED`, `CANCELLED`).
+- `createdAt`, `updatedAt`: Timestamps for auditing and sorting.
+- `startedAt`, `endedAt`: Timestamps for when the job actually started and finished. Set automatically when job is created.
+- `recordExpiresAt`: Unix epoch seconds for DynamoDB TTL/cleanup. Set automatically when job is created.
+- `resultLocation`: URL or S3 URI where the result can be retrieved, or empty if not available.
+- `resultType`: Optional. One of `S3`, `INLINE`, `URL`, or `null` if no result yet.
+- `result`: Inline result data (if small enough), or `null`.
+- `error`: Structured error object if the job failed.
+- `metadata`: Arbitrary metadata (e.g., who submitted the job, job type, tags).
+
+### Best Practices
+- `resultType` is optional and should only be set when a result is available. For jobs in progress, leave it `null` or unset.
+- Use `recordExpiresAt` to enable DynamoDB TTL for automatic cleanup of old jobs.
+- Use `metadata` for extensibility (e.g., tracking submitter, job type, or tags).
+
+## Usage Example
+
+```js
+const { AsyncJob } = dataAccess;
+
+// 1. Submit a new async job
+const job = await AsyncJob.create({
+  status: 'IN_PROGRESS',
+  metadata: { submittedBy: 'user123', jobType: 'export', tags: ['export'] },
+});
+
+// 2. Poll for job status
+const polledJob = await AsyncJob.findById(job.getId());
+if (polledJob.getStatus() === 'COMPLETED') {
+  // 3. Retrieve result
+  if (polledJob.getResultType() === 'S3') {
+    // Download from S3
+    const s3Url = polledJob.getResultLocation();
+    // ...
+  } else if (polledJob.getResultType() === 'INLINE') {
+    const result = polledJob.getResult();
+    // ...
+  }
+} else if (polledJob.getStatus() === 'FAILED') {
+  const error = polledJob.getError();
+  // Handle error
+}
+```
+
+## When to Use AsyncJob
+- For any API where work is performed asynchronously and clients must check back for results.
+- For workflows where results may be large (S3), small (inline), or may fail and need error reporting.
+- For jobs that should expire and be cleaned up automatically.
+
+See the `AsyncJob` model, schema, and integration/unit tests for more details and usage patterns. 

package/src/models/async-job/async-job.collection.js

@@ -0,0 +1,26 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * AsyncJobCollection - A collection class responsible for managing AsyncJob entities.
+ * Extends the BaseCollection to provide specific methods for interacting with AsyncJob records.
+ *
+ * @class AsyncJobCollection
+ * @extends BaseCollection
+ */
+class AsyncJobCollection extends BaseCollection {
+  // Add custom methods or overrides here if needed
+}
+
+export default AsyncJobCollection;

package/src/models/async-job/async-job.model.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import BaseModel from '../base/base.model.js';
+
+/**
+ * AsyncJob - A class representing an AsyncJob entity.
+ * Provides methods to access and manipulate AsyncJob-specific data.
+ *
+ * @class AsyncJob
+ * @extends BaseModel
+ */
+class AsyncJob extends BaseModel {
+  /**
+   * Async Job Status types.
+   * Any changes to this object needs to be reflected in the index.d.ts file as well.
+   */
+  static Status = {
+    IN_PROGRESS: 'IN_PROGRESS',
+    COMPLETED: 'COMPLETED',
+    FAILED: 'FAILED',
+    CANCELLED: 'CANCELLED',
+  };
+
+  /**
+   * Async Job Result types.
+   */
+  static ResultType = {
+    S3: 'S3',
+    INLINE: 'INLINE',
+    URL: 'URL',
+  };
+
+  // Add custom methods or overrides here if needed
+}
+
+export default AsyncJob;

package/src/models/async-job/async-job.schema.js

@@ -0,0 +1,65 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import { isObject, isValidUrl, isIsoDate } from '@adobe/spacecat-shared-utils';
+import SchemaBuilder from '../base/schema.builder.js';
+import AsyncJob from './async-job.model.js';
+import AsyncJobCollection from './async-job.collection.js';
+
+const schema = new SchemaBuilder(AsyncJob, AsyncJobCollection)
+  .withRecordExpiry(7)
+  .addAttribute('status', {
+    type: Object.values(AsyncJob.Status),
+    required: true,
+  })
+  .addAttribute('resultLocation', {
+    type: 'string',
+    validate: (value) => !value || isValidUrl(value) || value.startsWith('s3://'),
+  })
+  .addAttribute('resultType', {
+    type: 'string',
+    validate: (value) => !value || Object.values(AsyncJob.ResultType).includes(value),
+  })
+  .addAttribute('result', {
+    type: 'any',
+    validate: (value) => !value || isObject(value),
+  })
+  .addAttribute('error', {
+    type: 'map',
+    properties: {
+      code: { type: 'string' },
+      message: { type: 'string' },
+      details: { type: 'any' },
+    },
+    validate: (value) => !value || (isObject(value) && value.code && value.message),
+  })
+  .addAttribute('metadata', {
+    type: 'any',
+    validate: (value) => !value || isObject(value),
+  })
+  .addAttribute('startedAt', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    default: () => new Date().toISOString(),
+    validate: (value) => !value || isIsoDate(value),
+  })
+  .addAttribute('endedAt', {
+    type: 'string',
+    validate: (value) => !value || isIsoDate(value),
+  })
+  .addIndex(
+    { composite: ['status'] },
+    { composite: ['updatedAt'] },
+  );
+
+export default schema.build();

package/src/models/async-job/index.d.ts

@@ -0,0 +1,35 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import type { BaseCollection, BaseModel } from '../base';
+
+export interface AsyncJob extends BaseModel {
+    getStatus(): string;
+    getResultLocation(): string;
+    getResultType(): string;
+    getResult(): object;
+    getError(): { code: string; message: string; details?: object } | null;
+    getMetadata(): object | null;
+    getRecordExpiressAt(): number;
+    setStatus(status: string): void;
+    setResultLocation(location: string): void;
+    setResultType(type: string): void;
+    setResult(result: object): void;
+    setError(error: { code: string; message: string; details?: object }): void;
+    setMetadata(metadata: object): void;
+    setExpiresAt(expiresAt: number): void;
+}
+
+export interface AsyncJobCollection extends BaseCollection<AsyncJob> {
+    allByStatus(status: string): Promise<AsyncJob[]>;
+    findByStatus(status: string): Promise<AsyncJob | null>;
+}

package/src/models/async-job/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2025 Adobe. All rights reserved.
+ * This file is licensed to you under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License. You may obtain a copy
+ * of the License at http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software distributed under
+ * the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS
+ * OF ANY KIND, either express or implied. See the License for the specific language
+ * governing permissions and limitations under the License.
+ */
+
+import AsyncJob from './async-job.model.js';
+import AsyncJobCollection from './async-job.collection.js';
+
+export {
+  AsyncJob,
+  AsyncJobCollection,
+};

package/src/models/base/base.collection.js

@@ -422,7 +422,7 @@ class BaseCollection {
         validatedItems.push({ ...removeElectroProperties(Item), ...item });
       } catch (error) {
         if (error instanceof ElectroValidationError) {
-          errorItems.push({ item, error: new ValidationError(error) });
+          errorItems.push({ item, error: new ValidationError('Validation error', this, error) });
         }
       }
     });

package/src/models/base/entity.registry.js

@@ -14,6 +14,7 @@ import { DataAccessError } from '../../errors/index.js';
 import { collectionNameToEntityName, decapitalize } from '../../util/util.js';
 
 import ApiKeyCollection from '../api-key/api-key.collection.js';
+import AsyncJobCollection from '../async-job/async-job.collection.js';
 import AuditCollection from '../audit/audit.collection.js';
 import ConfigurationCollection from '../configuration/configuration.collection.js';
 import ExperimentCollection from '../experiment/experiment.collection.js';
@@ -30,6 +31,7 @@ import SiteTopPageCollection from '../site-top-page/site-top-page.collection.js'
 import SuggestionCollection from '../suggestion/suggestion.collection.js';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
+import AsyncJobSchema from '../async-job/async-job.schema.js';
 import AuditSchema from '../audit/audit.schema.js';
 import ConfigurationSchema from '../configuration/configuration.schema.js';
 import FixEntitySchema from '../fix-entity/fix-entity.schema.js';
@@ -127,6 +129,7 @@ class EntityRegistry {
 }
 
 EntityRegistry.registerEntity(ApiKeySchema, ApiKeyCollection);
+EntityRegistry.registerEntity(AsyncJobSchema, AsyncJobCollection);
 EntityRegistry.registerEntity(AuditSchema, AuditCollection);
 EntityRegistry.registerEntity(ConfigurationSchema, ConfigurationCollection);
 EntityRegistry.registerEntity(FixEntitySchema, FixEntityCollection);

package/src/models/index.d.ts

@@ -11,6 +11,7 @@
  */
 
 export type * from './audit';
+export type * from './async-job';
 export type * from './configuration';
 export type * from './base';
 export type * from './fix-entity';

package/src/models/index.js

@@ -11,6 +11,7 @@
  */
 
 export * from './api-key/index.js';
+export * from './async-job/index.js';
 export * from './audit/index.js';
 export * from './base/index.js';
 export * from './configuration/index.js';