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,9 @@ 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 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 +100,9 @@ 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 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 +240,9 @@ EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollec
 EntityRegistry.registerEntity(SentimentTopicSchema, SentimentTopicCollection);
 EntityRegistry.registerEntity(AccessGrantLogSchema, AccessGrantLogCollection);
 EntityRegistry.registerEntity(SiteImsOrgAccessSchema, SiteImsOrgAccessCollection);
+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/index.d.ts

@@ -40,6 +40,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

@@ -53,3 +53,6 @@ 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 './task-management-connection/index.js';
+export * from './ticket/index.js';
+export * from './ticket-suggestion/index.js';

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

@@ -0,0 +1,68 @@
+/*
+ * Copyright 2024 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, Ticket } from '../index';
+
+export interface TaskManagementConnection extends BaseModel {
+  /** Returns true when the connection is healthy and ready to create tickets. */
+  isActive(): boolean;
+  /**
+   * Persists status = 'requires_reauth'. Call this after a failed token refresh
+   * so the UI can prompt the user to reconnect.
+   */
+  markRequiresReauth(): Promise<TaskManagementConnection>;
+  /** Persists status = 'disabled'. */
+  markDisabled(): Promise<TaskManagementConnection>;
+  /** Persists status = 'error' after repeated API failures. */
+  markError(): Promise<TaskManagementConnection>;
+  /** Persists status = 'disconnected' (soft-delete on user revoke). */
+  markDisconnected(): Promise<TaskManagementConnection>;
+
+  getConnectedBy(): string;
+  getDisplayName(): string;
+  getInstanceUrl(): string;
+  getMetadata(): object;
+  getOrganizationId(): string;
+  getProvider(): string;
+  getStatus(): string;
+  getTickets(): Promise<Ticket[]>;
+
+  setMetadata(metadata: object): TaskManagementConnection;
+  setStatus(status: string): TaskManagementConnection;
+}
+
+export interface TaskManagementConnectionCollection extends BaseCollection<TaskManagementConnection> {
+  /**
+   * Returns the active connection for an org + provider pair used by the
+   * ticket-creation API before every ticket request, or null if none exists.
+   */
+  findActiveByOrganizationAndProvider(
+    organizationId: string,
+    provider: string,
+  ): Promise<TaskManagementConnection | null>;
+
+  allByOrganizationId(organizationId: string): Promise<TaskManagementConnection[]>;
+  allByOrganizationIdAndProvider(
+    organizationId: string,
+    provider: string,
+  ): Promise<TaskManagementConnection[]>;
+  allByOrganizationIdAndProviderAndStatus(
+    organizationId: string,
+    provider: string,
+    status: string,
+  ): Promise<TaskManagementConnection[]>;
+  findByOrganizationIdAndProviderAndStatus(
+    organizationId: string,
+    provider: string,
+    status: string,
+  ): Promise<TaskManagementConnection | null>;
+}

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

@@ -0,0 +1,21 @@
+/*
+ * Copyright 2024 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 TaskManagementConnection from './task-management-connection.model.js';
+import TaskManagementConnectionCollection from './task-management-connection.collection.js';
+import { validateMetadata } from './metadata-validator.js';
+
+export {
+  TaskManagementConnection,
+  TaskManagementConnectionCollection,
+  validateMetadata,
+};

packages/spacecat-shared-data-access/src/models/task-management-connection/metadata-validator.js

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2024 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 { ValidationError } from '../../errors/index.js';
+
+// UUID regex used by the spec for cloudId format validation.
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/**
+ * Per-provider metadata schemas (mirrors spec §Metadata Validation Strategy).
+ *
+ * Each schema defines:
+ *   required   — fields that MUST be present
+ *   properties — per-field validators (functions that return an error string or null)
+ *   allowed    — exhaustive list of permitted keys (enforces additionalProperties: false)
+ *
+ * Design: plain JS instead of ajv so no new production dependency is needed.
+ * The logic is equivalent to the spec's JSON Schema: required fields, a UUID
+ * pattern constraint, and additionalProperties: false.
+ */
+const METADATA_SCHEMAS = {
+  jira_cloud: {
+    // Aligns with mysticat-data-service PR #720:
+    //   - cloudId (required) is Atlassian's stable workspace UUID used to build API URLs;
+    //     enforced as UUID format by a DB CHECK constraint.
+    //   - scopes (optional) is the array from the Atlassian accessible-resources response;
+    //     stored so permission gaps can be detected without re-calling Atlassian (e.g. missing
+    //     manage:jira-webhook when v2 webhooks land).
+    //   - siteName and siteUrl are NOT stored in metadata — they live in the dedicated
+    //     display_name and instance_url columns (see PR #720 mysticat-data-service).
+    required: ['cloudId'],
+    allowed: new Set(['cloudId', 'scopes']),
+    properties: {
+      cloudId: (v) => (UUID_REGEX.test(v) ? null : 'cloudId must be a valid UUID'),
+      scopes: (v) => (Array.isArray(v) && v.every((s) => typeof s === 'string')
+        ? null
+        : 'scopes must be an array of strings'),
+    },
+  },
+  jira_corp: {
+    required: ['baseUrl'],
+    allowed: new Set(['baseUrl', 'projectCategory']),
+    properties: {
+      baseUrl: (v) => (typeof v === 'string' && v.startsWith('https://') ? null : 'baseUrl must be a valid https:// URI'),
+      projectCategory: (v) => (typeof v === 'string' ? null : 'projectCategory must be a string'),
+    },
+  },
+};
+
+/**
+ * Validates provider-specific connection metadata before a DB write.
+ *
+ * Called on connection INSERT and UPDATE (auth-service path and future edit API).
+ * Unknown providers are rejected — no silent passthrough.
+ *
+ * @param {string} provider - e.g. 'jira_cloud'
+ * @param {object} metadata - The JSONB metadata object to validate
+ * @throws {ValidationError} On missing fields, wrong types, unknown keys, or unknown provider
+ */
+export function validateMetadata(provider, metadata) {
+  const schema = METADATA_SCHEMAS[provider];
+  if (!schema) {
+    // Providers without a schema (asana, workfront) are v2 placeholders — reject
+    // all writes until a schema is defined so incomplete data never reaches the DB.
+    throw new ValidationError(`No metadata schema for provider: ${provider}`);
+  }
+
+  const { required, allowed, properties } = schema;
+
+  for (const field of required) {
+    if (metadata[field] === undefined || metadata[field] === null) {
+      throw new ValidationError(`metadata.${field} is required`);
+    }
+  }
+
+  for (const [field, validate] of Object.entries(properties)) {
+    if (metadata[field] !== undefined) {
+      const err = validate(metadata[field]);
+      if (err) {
+        throw new ValidationError(`Invalid metadata: ${err}`);
+      }
+    }
+  }
+
+  // additionalProperties: false — reject any key not in the allowed set
+  const extraKeys = Object.keys(metadata).filter((k) => !allowed.has(k));
+  if (extraKeys.length > 0) {
+    throw new ValidationError(`Unexpected metadata properties for ${provider}: ${extraKeys.join(', ')}`);
+  }
+}

packages/spacecat-shared-data-access/src/models/task-management-connection/task-management-connection.collection.js

@@ -0,0 +1,61 @@
+/*
+ * Copyright 2024 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 { isValidUUID } from '@adobe/spacecat-shared-utils';
+
+import { ValidationError } from '../../errors/index.js';
+import BaseCollection from '../base/base.collection.js';
+import TaskManagementConnection from './task-management-connection.model.js';
+
+/**
+ * TaskManagementConnectionCollection — manages TaskManagementConnection entities.
+ *
+ * Key query the ticket-creation API relies on:
+ *   `findActiveByOrganizationAndProvider(orgId, provider)` — returns the single
+ *   active connection for a given org + provider pair, or null if none exists.
+ *
+ * @class TaskManagementConnectionCollection
+ * @extends BaseCollection
+ */
+class TaskManagementConnectionCollection extends BaseCollection {
+  static COLLECTION_NAME = 'TaskManagementConnectionCollection';
+
+  /**
+   * Returns the single active connection for an organization and provider, or
+   * null when the org has not connected that provider (or the connection is
+   * in a degraded / disconnected state).
+   *
+   * The API layer calls this before every ticket-creation request and returns
+   * 409 Conflict when no active connection is found.
+   *
+   * @param {string} organizationId - The organization UUID.
+   * @param {string} provider - The provider key, e.g. 'jira_cloud'.
+   * @returns {Promise<TaskManagementConnection|null>}
+   * @throws {ValidationError} When organizationId or provider is missing.
+   */
+  async findActiveByOrganizationAndProvider(organizationId, provider) {
+    if (!isValidUUID(organizationId)) {
+      throw new ValidationError('organizationId must be a valid UUID', this);
+    }
+    if (!provider) {
+      throw new ValidationError('provider is required', this);
+    }
+
+    return this.findByOrganizationIdAndProviderAndStatus(
+      organizationId,
+      provider,
+      TaskManagementConnection.STATUSES.ACTIVE,
+    );
+  }
+}
+
+export default TaskManagementConnectionCollection;