feat(SITES-44690): add TaskManagementConnection, Ticket, TicketSuggestion, IdempotencyKey, and OAuthNonce data models

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

@@ -55,6 +55,11 @@ import SentimentGuidelineCollection from '../sentiment-guideline/sentiment-guide
 import SentimentTopicCollection from '../sentiment-topic/sentiment-topic.collection.js';
 import AccessGrantLogCollection from '../access-grant-log/access-grant-log.collection.js';
 import SiteImsOrgAccessCollection from '../site-ims-org-access/site-ims-org-access.collection.js';
+import IdempotencyKeyCollection from '../idempotency-key/idempotency-key.collection.js';
+import OAuthNonceCollection from '../oauth-nonce/oauth-nonce.collection.js';
+import TaskManagementConnectionCollection from '../task-management-connection/task-management-connection.collection.js';
+import TicketCollection from '../ticket/ticket.collection.js';
+import TicketSuggestionCollection from '../ticket-suggestion/ticket-suggestion.collection.js';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
 import AsyncJobSchema from '../async-job/async-job.schema.js';
@@ -97,6 +102,11 @@ import SentimentGuidelineSchema from '../sentiment-guideline/sentiment-guideline
 import SentimentTopicSchema from '../sentiment-topic/sentiment-topic.schema.js';
 import AccessGrantLogSchema from '../access-grant-log/access-grant-log.schema.js';
 import SiteImsOrgAccessSchema from '../site-ims-org-access/site-ims-org-access.schema.js';
+import IdempotencyKeySchema from '../idempotency-key/idempotency-key.schema.js';
+import OAuthNonceSchema from '../oauth-nonce/oauth-nonce.schema.js';
+import TaskManagementConnectionSchema from '../task-management-connection/task-management-connection.schema.js';
+import TicketSchema from '../ticket/ticket.schema.js';
+import TicketSuggestionSchema from '../ticket-suggestion/ticket-suggestion.schema.js';
 
 /**
  * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
@@ -234,6 +244,11 @@ EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollec
 EntityRegistry.registerEntity(SentimentTopicSchema, SentimentTopicCollection);
 EntityRegistry.registerEntity(AccessGrantLogSchema, AccessGrantLogCollection);
 EntityRegistry.registerEntity(SiteImsOrgAccessSchema, SiteImsOrgAccessCollection);
+EntityRegistry.registerEntity(IdempotencyKeySchema, IdempotencyKeyCollection);
+EntityRegistry.registerEntity(OAuthNonceSchema, OAuthNonceCollection);
+EntityRegistry.registerEntity(TaskManagementConnectionSchema, TaskManagementConnectionCollection);
+EntityRegistry.registerEntity(TicketSchema, TicketCollection);
+EntityRegistry.registerEntity(TicketSuggestionSchema, TicketSuggestionCollection);
 EntityRegistry.defaultEntities = { ...EntityRegistry.entities };
 
 export default EntityRegistry;

packages/spacecat-shared-data-access/src/models/idempotency-key/idempotency-key.collection.js

@@ -0,0 +1,89 @@
+/*
+ * 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, isValidUUID } from '@adobe/spacecat-shared-utils';
+
+import { DataAccessError, ValidationError } from '../../errors/index.js';
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * IdempotencyKeyCollection — manages IdempotencyKey entities.
+ *
+ * Auto-generated index query methods (via schema references):
+ *   allByOrganizationId(organizationId) — all keys for an organization
+ *
+ * @class IdempotencyKeyCollection
+ * @extends BaseCollection
+ */
+class IdempotencyKeyCollection extends BaseCollection {
+  static COLLECTION_NAME = 'IdempotencyKeyCollection';
+
+  /**
+   * Finds a non-expired idempotency key by its value and organization.
+   *
+   * Returns null when:
+   *   - No key exists with that value for the organization
+   *   - The key exists but has expired (expires_at < NOW())
+   *
+   * @param {string} key - The idempotency key value.
+   * @param {string} organizationId - The organization UUID.
+   * @returns {Promise<import('./idempotency-key.model.js').default|null>}
+   */
+  async findActiveKey(key, organizationId) {
+    if (!hasText(key)) {
+      throw new ValidationError('key is required', this);
+    }
+    if (!isValidUUID(organizationId)) {
+      throw new ValidationError('organizationId must be a valid UUID', this);
+    }
+
+    const { data, error } = await this.postgrestService
+      .from(this.tableName)
+      .select()
+      .eq('key', key)
+      .eq('organization_id', organizationId)
+      .gt('expires_at', new Date().toISOString())
+      .limit(1);
+
+    if (error) {
+      throw new DataAccessError('Failed to find active idempotency key', { entityName: 'IdempotencyKey' }, error);
+    }
+
+    if (!data || data.length === 0) {
+      return null;
+    }
+
+    return this.createInstanceFromRow(data[0]);
+  }
+
+  /**
+   * Deletes all expired idempotency keys.
+   * Called by the cleanup scheduler (every 5 minutes).
+   *
+   * @returns {Promise<number>} Number of expired keys deleted.
+   */
+  async deleteExpired() {
+    const { data, error } = await this.postgrestService
+      .from(this.tableName)
+      .delete()
+      .lt('expires_at', new Date().toISOString())
+      .select('id');
+
+    if (error) {
+      throw new DataAccessError('Failed to delete expired idempotency keys', { entityName: 'IdempotencyKey' }, error);
+    }
+
+    return (data ?? []).length;
+  }
+}
+
+export default IdempotencyKeyCollection;

packages/spacecat-shared-data-access/src/models/idempotency-key/idempotency-key.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';
+
+/**
+ * IdempotencyKey — deduplicates concurrent or retried requests using the
+ * Stripe idempotency pattern.
+ *
+ * Status lifecycle:
+ *   processing → completed   (cached success response)
+ *   processing → failed      (cached error response, client must generate new key to retry)
+ *
+ * Keys are scoped to (key, organizationId, endpoint) — cross-org collision is impossible
+ * and the same key can be used independently across different operations.
+ *
+ * Keys expire after 24 hours (or shorter for ephemeral locks like token refresh dedup).
+ *
+ * @class IdempotencyKey
+ * @extends BaseModel
+ */
+class IdempotencyKey extends BaseModel {
+  static ENTITY_NAME = 'IdempotencyKey';
+
+  static STATUSES = {
+    PROCESSING: 'processing',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+  };
+}
+
+export default IdempotencyKey;

packages/spacecat-shared-data-access/src/models/idempotency-key/idempotency-key.schema.js

@@ -0,0 +1,51 @@
+/*
+ * 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 { isIsoDate } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import IdempotencyKey from './idempotency-key.model.js';
+import IdempotencyKeyCollection from './idempotency-key.collection.js';
+
+// idempotency_keys table has updated_at but no updated_by column.
+const schema = new SchemaBuilder(IdempotencyKey, IdempotencyKeyCollection)
+  .addAttribute('updatedBy', { type: 'string', required: false, postgrestIgnore: true })
+  .addReference('belongs_to', 'Organization')
+  .addAttribute('key', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('endpoint', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('status', {
+    type: Object.values(IdempotencyKey.STATUSES),
+    required: true,
+    default: IdempotencyKey.STATUSES.PROCESSING,
+  })
+  .addAttribute('response', {
+    type: 'any',
+    required: false,
+  })
+  .addAttribute('expiresAt', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isIsoDate(value),
+  });
+
+export default schema.build();

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

@@ -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 type { BaseCollection, BaseModel, Organization } from '../index';
+
+export interface IdempotencyKey extends BaseModel {
+  getEndpoint(): string;
+  getExpiresAt(): string;
+  getKey(): string;
+  getOrganization(): Promise<Organization>;
+  getOrganizationId(): string;
+  getResponse(): Record<string, unknown> | null;
+  getStatus(): string;
+
+  setResponse(response: Record<string, unknown> | null): IdempotencyKey;
+  setStatus(status: string): IdempotencyKey;
+}
+
+export interface IdempotencyKeyCollection extends BaseCollection<IdempotencyKey> {
+  allByOrganizationId(organizationId: string): Promise<IdempotencyKey[]>;
+
+  /**
+   * Finds a non-expired idempotency key by its value and organization.
+   * Returns null when no active key exists.
+   */
+  findActiveKey(key: string, organizationId: string): Promise<IdempotencyKey | null>;
+
+  /**
+   * Deletes all expired idempotency keys. Returns the number deleted.
+   */
+  deleteExpired(): Promise<number>;
+}

packages/spacecat-shared-data-access/src/models/idempotency-key/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 IdempotencyKey from './idempotency-key.model.js';
+import IdempotencyKeyCollection from './idempotency-key.collection.js';
+
+export {
+  IdempotencyKey,
+  IdempotencyKeyCollection,
+};

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

@@ -30,6 +30,8 @@ export type * from './import-url';
 export type * from './key-event';
 export type * from './latest-audit';
 export type * from './opportunity';
+export type * from './idempotency-key';
+export type * from './oauth-nonce';
 export type * from './organization';
 export type * from './page-citability';
 export type * from './page-intent';
@@ -40,6 +42,9 @@ export type * from './scrape-job';
 export type * from './scrape-url';
 export type * from './sentiment-guideline';
 export type * from './sentiment-topic';
+export type * from './task-management-connection';
+export type * from './ticket';
+export type * from './ticket-suggestion';
 export type * from './site';
 export type * from './site-candidate';
 export type * from './site-enrollment';

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

@@ -54,3 +54,8 @@ export * from './page-citability/index.js';
 export * from './plg-onboarding/index.js';
 export * from './sentiment-guideline/index.js';
 export * from './sentiment-topic/index.js';
+export * from './idempotency-key/index.js';
+export * from './oauth-nonce/index.js';
+export * from './task-management-connection/index.js';
+export * from './ticket/index.js';
+export * from './ticket-suggestion/index.js';

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

@@ -0,0 +1,26 @@
+/*
+ * 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 } from '../index';
+
+export interface OAuthNonce extends BaseModel {
+  getNonce(): string;
+  getExpiresAt(): string;
+}
+
+export interface OAuthNonceCollection extends BaseCollection<OAuthNonce> {
+  /**
+   * Atomically deletes a nonce by its value.
+   * Returns the number of rows deleted (1 = consumed, 0 = not found or already consumed).
+   */
+  delete(keys: { nonce: string }): Promise<number>;
+}

packages/spacecat-shared-data-access/src/models/oauth-nonce/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 OAuthNonce from './oauth-nonce.model.js';
+import OAuthNonceCollection from './oauth-nonce.collection.js';
+
+export {
+  OAuthNonce,
+  OAuthNonceCollection,
+};