feat: experimentation engine

packages/spacecat-shared-data-access/src/models/base/entity.registry.js

@@ -21,6 +21,7 @@ import ConfigurationCollection from '../configuration/configuration.collection.j
 import ConsumerCollection from '../consumer/consumer.collection.js';
 import ExperimentCollection from '../experiment/experiment.collection.js';
 import EntitlementCollection from '../entitlement/entitlement.collection.js';
+import GeoExperimentCollection from '../geo-experiment/geo-experiment.collection.js';
 import FixEntityCollection from '../fix-entity/fix-entity.collection.js';
 import FixEntitySuggestionCollection from '../fix-entity-suggestion/fix-entity-suggestion.collection.js';
 import ImportJobCollection from '../import-job/import-job.collection.js';
@@ -57,6 +58,7 @@ import AuditSchema from '../audit/audit.schema.js';
 import AuditUrlSchema from '../audit-url/audit-url.schema.js';
 import ConsumerSchema from '../consumer/consumer.schema.js';
 import EntitlementSchema from '../entitlement/entitlement.schema.js';
+import GeoExperimentSchema from '../geo-experiment/geo-experiment.schema.js';
 import FixEntitySchema from '../fix-entity/fix-entity.schema.js';
 import FixEntitySuggestionSchema from '../fix-entity-suggestion/fix-entity-suggestion.schema.js';
 import ExperimentSchema from '../experiment/experiment.schema.js';
@@ -189,6 +191,7 @@ EntityRegistry.registerEntity(AuditSchema, AuditCollection);
 EntityRegistry.registerEntity(AuditUrlSchema, AuditUrlCollection);
 EntityRegistry.registerEntity(ConsumerSchema, ConsumerCollection);
 EntityRegistry.registerEntity(EntitlementSchema, EntitlementCollection);
+EntityRegistry.registerEntity(GeoExperimentSchema, GeoExperimentCollection);
 EntityRegistry.registerEntity(FixEntitySchema, FixEntityCollection);
 EntityRegistry.registerEntity(FixEntitySuggestionSchema, FixEntitySuggestionCollection);
 EntityRegistry.registerEntity(ExperimentSchema, ExperimentCollection);

packages/spacecat-shared-data-access/src/models/geo-experiment/geo-experiment.collection.js

@@ -0,0 +1,43 @@
+/*
+ * Copyright 2026 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 { hasText } from '@adobe/spacecat-shared-utils';
+import BaseCollection from '../base/base.collection.js';
+
+class GeoExperimentCollection extends BaseCollection {
+  static COLLECTION_NAME = 'GeoExperimentCollection';
+
+  /**
+   * Gets all geo experiments for a site, ordered by most recently updated.
+   *
+   * @param {string} siteId - The site ID.
+   * @param {object} [options={}] - Query options (limit, cursor).
+   * @returns {Promise<{data: GeoExperiment[], cursor: string|null}>} Paginated results.
+   */
+  async allBySiteId(siteId, options = {}) {
+    if (!hasText(siteId)) {
+      throw new Error('SiteId is required');
+    }
+
+    const result = await this.allByIndexKeys(
+      { siteId },
+      { ...options, returnCursor: true },
+    );
+
+    return {
+      data: result.data || [],
+      cursor: result.cursor,
+    };
+  }
+}
+
+export default GeoExperimentCollection;

packages/spacecat-shared-data-access/src/models/geo-experiment/geo-experiment.model.js

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2026 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';
+
+class GeoExperiment extends BaseModel {
+  static ENTITY_NAME = 'GeoExperiment';
+
+  static DEFAULT_UPDATED_BY = 'spacecat';
+
+  static TYPES = {
+    ONSITE_OPPORTUNITY_DEPLOYMENT: 'onsite_opportunity_deployment',
+  };
+
+  static STATUSES = {
+    GENERATING_BASELINE: 'GENERATING_BASELINE',
+    IN_PROGRESS: 'IN_PROGRESS',
+    COMPLETED: 'COMPLETED',
+    FAILED: 'FAILED',
+  };
+
+  static PHASES = {
+    PRE_ANALYSIS_SUBMITTED: 'pre_analysis_submitted',
+    PRE_ANALYSIS_DONE: 'pre_analysis_done',
+    DEPLOYMENT_STARTED: 'deployment_started',
+    DEPLOYMENT_COMPLETED: 'deployment_completed',
+    POST_ANALYSIS_SUBMITTED: 'post_analysis_submitted',
+    POST_ANALYSIS_DONE: 'post_analysis_done',
+  };
+}
+
+export default GeoExperiment;

packages/spacecat-shared-data-access/src/models/geo-experiment/geo-experiment.schema.js

@@ -0,0 +1,93 @@
+/*
+ * Copyright 2026 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.
+ */
+
+/* c8 ignore start */
+
+import {
+  hasText,
+  isInteger,
+  isObject,
+  isValidUUID,
+} from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import GeoExperiment from './geo-experiment.model.js';
+import GeoExperimentCollection from './geo-experiment.collection.js';
+
+const schema = new SchemaBuilder(GeoExperiment, GeoExperimentCollection)
+  .addReference('belongs_to', 'Site')
+  .addReference('belongs_to', 'Opportunity', [], { required: false })
+  .addAttribute('preScheduleId', {
+    type: 'string',
+    validate: (value) => !value || hasText(value),
+  })
+  .addAttribute('postScheduleId', {
+    type: 'string',
+    validate: (value) => !value || hasText(value),
+  })
+  .addAttribute('type', {
+    type: Object.values(GeoExperiment.TYPES),
+    required: true,
+  })
+  .addAttribute('status', {
+    type: Object.values(GeoExperiment.STATUSES),
+    required: true,
+  })
+  .addAttribute('phase', {
+    type: Object.values(GeoExperiment.PHASES),
+    required: true,
+  })
+  .addAttribute('suggestionIds', {
+    type: 'list',
+    items: {
+      type: 'string',
+      validate: (value) => isValidUUID(value),
+    },
+    default: () => [],
+  })
+  .addAttribute('name', {
+    type: 'string',
+    required: true,
+    validate: (value) => hasText(value),
+  })
+  .addAttribute('promptsCount', {
+    type: 'number',
+    default: 0,
+    validate: (value) => isInteger(value) && value >= 0,
+  })
+  .addAttribute('promptsLocation', {
+    type: 'string',
+    validate: (value) => !value || hasText(value),
+  })
+  .addAttribute('startTime', {
+    type: 'string',
+    validate: (value) => !value || hasText(value),
+  })
+  .addAttribute('endTime', {
+    type: 'string',
+    validate: (value) => !value || hasText(value),
+  })
+  .addAttribute('metadata', {
+    type: 'any',
+    validate: (value) => !value || isObject(value),
+  })
+  .addAttribute('error', {
+    type: 'any',
+    validate: (value) => !value || isObject(value),
+  })
+  .addAttribute('updatedBy', {
+    type: 'string',
+    default: GeoExperiment.DEFAULT_UPDATED_BY,
+    validate: (value) => hasText(value),
+  });
+
+export default schema.build();

packages/spacecat-shared-data-access/src/models/geo-experiment/index.d.ts

@@ -0,0 +1,71 @@
+/*
+ * Copyright 2026 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,
+  Opportunity,
+  PaginatedResult,
+  QueryOptions,
+  Site,
+} from '../index';
+
+export interface GeoExperiment extends BaseModel {
+  getSiteId(): string;
+  getOpportunityId(): string | undefined;
+  getSite(): Promise<Site>;
+  getOpportunity(): Promise<Opportunity>;
+  getPreScheduleId(): string | undefined;
+  getPostScheduleId(): string | undefined;
+  getType(): string;
+  getPhase(): string;
+  getStatus(): string;
+  getSuggestionIds(): string[];
+  getPromptsLocation(): string | undefined;
+  getName(): string;
+  getPromptsCount(): number;
+  getStartTime(): string | undefined;
+  getEndTime(): string | undefined;
+  getMetadata(): object | undefined;
+  getError(): object | undefined;
+  getUpdatedBy(): string;
+
+  setSiteId(siteId: string): GeoExperiment;
+  setOpportunityId(opportunityId?: string): GeoExperiment;
+  setPreScheduleId(preScheduleId?: string): GeoExperiment;
+  setPostScheduleId(postScheduleId?: string): GeoExperiment;
+  setType(type: string): GeoExperiment;
+  setPhase(phase: string): GeoExperiment;
+  setStatus(status: string): GeoExperiment;
+  setSuggestionIds(suggestionIds: string[]): GeoExperiment;
+  setPromptsLocation(promptsLocation?: string): GeoExperiment;
+  setName(name: string): GeoExperiment;
+  setPromptsCount(promptsCount: number): GeoExperiment;
+  setStartTime(startTime?: string): GeoExperiment;
+  setEndTime(endTime?: string): GeoExperiment;
+  setMetadata(metadata?: object): GeoExperiment;
+  setError(error?: object): GeoExperiment;
+  setUpdatedBy(updatedBy: string): GeoExperiment;
+}
+
+export interface GeoExperimentCollection extends BaseCollection<GeoExperiment> {
+  allBySiteId(siteId: string, options?: QueryOptions): Promise<PaginatedResult<GeoExperiment>>;
+  findBySiteId(siteId: string): Promise<GeoExperiment | null>;
+  allByOpportunityId(
+    opportunityId: string,
+    options?: QueryOptions,
+  ): Promise<GeoExperiment[] | PaginatedResult<GeoExperiment>>;
+  findByOpportunityId(
+    opportunityId: string,
+    options?: QueryOptions,
+  ): Promise<GeoExperiment | null>;
+}

packages/spacecat-shared-data-access/src/models/geo-experiment/index.js

@@ -0,0 +1,19 @@
+/*
+ * Copyright 2026 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 GeoExperiment from './geo-experiment.model.js';
+import GeoExperimentCollection from './geo-experiment.collection.js';
+
+export {
+  GeoExperiment,
+  GeoExperimentCollection,
+};

packages/spacecat-shared-data-access/src/models/index.d.ts

@@ -19,6 +19,7 @@ export type * from './base';
 export type * from './configuration';
 export type * from './consumer';
 export type * from './entitlement';
+export type * from './geo-experiment';
 export type * from './experiment';
 export type * from './fix-entity';
 export type * from './fix-entity-suggestion';

packages/spacecat-shared-data-access/src/models/index.js

@@ -19,6 +19,7 @@ export * from './base/index.js';
 export * from './configuration/index.js';
 export * from './consumer/index.js';
 export * from './entitlement/index.js';
+export * from './geo-experiment/index.js';
 export * from './fix-entity/index.js';
 export * from './fix-entity-suggestion/index.js';
 export * from './experiment/index.js';

packages/spacecat-shared-data-access/src/service/index.d.ts

@@ -19,6 +19,7 @@ import type { AuditUrlCollection } from '../models/audit-url';
 import type { ConfigurationCollection } from '../models/configuration';
 import type { ConsumerCollection } from '../models/consumer';
 import type { EntitlementCollection } from '../models/entitlement';
+import type { GeoExperimentCollection } from '../models/geo-experiment';
 import type { ExperimentCollection } from '../models/experiment';
 import type { FixEntityCollection } from '../models/fix-entity';
 import type { FixEntitySuggestionCollection } from '../models/fix-entity-suggestion';
@@ -68,6 +69,7 @@ export interface DataAccess {
   Configuration: ConfigurationCollection;
   Consumer: ConsumerCollection;
   Entitlement: EntitlementCollection;
+  GeoExperiment: GeoExperimentCollection;
   Experiment: ExperimentCollection;
   FixEntity: FixEntityCollection;
   FixEntitySuggestion: FixEntitySuggestionCollection;