@adobe/spacecat-shared-data-access 3.80.0 → 4.0.0

package/src/models/preflight/preflight.schema.js

@@ -17,6 +17,11 @@ import SchemaBuilder from '../base/schema.builder.js';
 import Preflight from './preflight.model.js';
 import PreflightCollection from './preflight.collection.js';
 
+// SITES-47254: `startedAt`, `result`, and `error` live only on AsyncJob now —
+// the underlying preflights table no longer carries them. Consumers fetch the
+// joined AsyncJob (e.g., `await preflight.getAsyncJob()`) for lifecycle
+// internals; `status` and `endedAt` remain here as a denormalized cache the
+// projector keeps in sync.
 const schema = new SchemaBuilder(Preflight, PreflightCollection)
   .addReference('belongs_to', 'Site', [], { required: true })
   .addReference('belongs_to', 'AsyncJob', [], { required: true })
@@ -30,34 +35,22 @@ const schema = new SchemaBuilder(Preflight, PreflightCollection)
     required: true,
     default: Preflight.Status.IN_PROGRESS,
   })
-  // `createdBy` and `error` use type 'any' (matching neighbor `result`) because
-  // ElectroDB's `map` type requires a `properties` schema for every sub-key,
-  // and the validate function below already enforces the precise shape — a
-  // duplicate `properties` declaration adds nothing. Declaring `type: 'map'`
-  // here without `properties` was the original definition and throws
-  // `InvalidAttributeDefinition` at Service construction, blocking any
-  // downstream consumer that builds a v1 `new Service(EntityRegistry.getEntities())`
-  // (e.g. spacecat-api-service `fixes.test.js`).
+  // `createdBy` uses type 'any' because ElectroDB's `map` type requires a
+  // `properties` schema for every sub-key, and the validate function below
+  // already enforces the precise shape — a duplicate `properties` declaration
+  // adds nothing. Declaring `type: 'map'` here without `properties` was the
+  // original definition and throws `InvalidAttributeDefinition` at Service
+  // construction, blocking any downstream consumer that builds a v1
+  // `new Service(EntityRegistry.getEntities())` (e.g. spacecat-api-service
+  // `fixes.test.js`).
   .addAttribute('createdBy', {
     type: 'any',
     required: true,
     validate: (value) => isObject(value) && typeof value.email === 'string' && value.email.length > 0,
   })
-  .addAttribute('startedAt', {
-    type: 'string',
-    validate: (value) => !value || isIsoDate(value),
-  })
   .addAttribute('endedAt', {
     type: 'string',
     validate: (value) => !value || isIsoDate(value),
-  })
-  .addAttribute('result', {
-    type: 'any',
-    validate: (value) => !value || isObject(value),
-  })
-  .addAttribute('error', {
-    type: 'any',
-    validate: (value) => !value || (isObject(value) && typeof value.code === 'string' && value.code.length > 0 && typeof value.message === 'string' && value.message.length > 0),
   });
 
 export default schema.build();

package/src/models/task-management-connection/index.d.ts

@@ -0,0 +1,82 @@
+/*
+ * 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, 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 = 'active' after a successful re-authorization. */
+  markActive(): Promise<TaskManagementConnection>;
+  /** Persists status = 'disconnected' (soft-delete on user revoke). */
+  markDisconnected(): Promise<TaskManagementConnection>;
+
+  getConnectedAt(): string | null;
+  getConnectedBy(): string;
+  getDisplayName(): string;
+  getErrorMessage(): string | null;
+  getExternalInstanceId(): string;
+  getInstanceUrl(): string;
+  getLastUsedAt(): string | null;
+  getMetadata(): object;
+  getOrganization(): Promise<Organization>;
+  getOrganizationId(): string;
+  getProvider(): string;
+  getStatus(): string;
+  getTickets(): Promise<Ticket[]>;
+
+  setConnectedAt(timestamp: string): TaskManagementConnection;
+  setDisplayName(name: string): TaskManagementConnection;
+  setErrorMessage(message: string | null): TaskManagementConnection;
+  setInstanceUrl(url: string): TaskManagementConnection;
+  setLastUsedAt(timestamp: string): TaskManagementConnection;
+  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>;
+}

package/src/models/task-management-connection/index.js

@@ -0,0 +1,21 @@
+/*
+ * 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 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,
+};

package/src/models/task-management-connection/metadata-validator.js

@@ -0,0 +1,97 @@
+/*
+ * 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 { 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.
+ */
+// v1: only jira_cloud is supported. Add jira_corp, asana, workfront schemas here
+// when the corresponding provider value is added to TaskManagementConnection.PROVIDERS.
+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'),
+    },
+  },
+};
+
+/**
+ * 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}`);
+  }
+
+  if (metadata === null || metadata === undefined || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    throw new ValidationError('metadata must be a non-null object');
+  }
+
+  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(', ')}`);
+  }
+}

package/src/models/task-management-connection/task-management-connection.collection.js

@@ -0,0 +1,61 @@
+/*
+ * 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 { 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;

package/src/models/task-management-connection/task-management-connection.model.js

@@ -0,0 +1,119 @@
+/*
+ * 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';
+
+/**
+ * TaskManagementConnection — one OAuth connection from an organization to a
+ * task-management provider (e.g. Jira Cloud).
+ *
+ * Status lifecycle (per architecture spec):
+ *   active           → tokens are valid, tickets can be created
+ *   disabled         → admin-disabled; no tickets until re-enabled
+ *   requires_reauth  → refresh token expired/revoked, user must reconnect
+ *   error            → repeated API failures; connection degraded
+ *   disconnected     → explicitly deleted by the user (v1 soft-delete)
+ *
+ * Provider-specific config lives in `metadata` as jsonb (jira_cloud: { cloudId, scopes }).
+ * Display fields (siteName, siteUrl) live in the dedicated displayName/instanceUrl columns.
+ *
+ * @class TaskManagementConnection
+ * @extends BaseModel
+ */
+class TaskManagementConnection extends BaseModel {
+  static ENTITY_NAME = 'TaskManagementConnection';
+
+  /** Supported task-management providers. */
+  static PROVIDERS = {
+    JIRA_CLOUD: 'jira_cloud',
+  };
+
+  /**
+   * Connection health statuses (per architecture spec PR #150).
+   *
+   * DISCONNECTED is a v1 extension — it represents the "deleted" lifecycle
+   * event as a soft-delete so audit history is preserved. The spec hard-deletes
+   * the row; v1 keeps it with status='disconnected' until a GC job removes it.
+   */
+  static STATUSES = {
+    ACTIVE: 'active',
+    DISABLED: 'disabled',
+    REQUIRES_REAUTH: 'requires_reauth',
+    ERROR: 'error',
+    DISCONNECTED: 'disconnected',
+  };
+
+  /**
+   * Returns true when this connection is healthy and ready to create tickets.
+   *
+   * @returns {boolean}
+   */
+  isActive() {
+    return this.getStatus() === TaskManagementConnection.STATUSES.ACTIVE;
+  }
+
+  /**
+   * Marks the connection as active. Called by auth-service after a successful
+   * re-authorization to restore a connection from requires_reauth state.
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markActive() {
+    this.setStatus(TaskManagementConnection.STATUSES.ACTIVE);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as requiring re-authentication (e.g. after a failed
+   * token refresh). Persists immediately so other services see the degraded
+   * state without waiting for the next GC cycle.
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markRequiresReauth() {
+    this.setStatus(TaskManagementConnection.STATUSES.REQUIRES_REAUTH);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as disabled (e.g. admin-disabled).
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markDisabled() {
+    this.setStatus(TaskManagementConnection.STATUSES.DISABLED);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as in an error state (repeated API failures).
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markError() {
+    this.setStatus(TaskManagementConnection.STATUSES.ERROR);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as disconnected (user-initiated soft-delete).
+   * v1 preserves the row for audit; a GC job handles eventual hard deletion.
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markDisconnected() {
+    this.setStatus(TaskManagementConnection.STATUSES.DISCONNECTED);
+    return this.save();
+  }
+}
+
+export default TaskManagementConnection;

package/src/models/task-management-connection/task-management-connection.schema.js

@@ -0,0 +1,111 @@
+/*
+ * 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, isValidUrl } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import TaskManagementConnection from './task-management-connection.model.js';
+import TaskManagementConnectionCollection from './task-management-connection.collection.js';
+import { validateMetadata } from './metadata-validator.js';
+
+// Sort key [provider, status] on the Organization GSI lets the collection method
+// findActiveByOrganizationAndProvider() resolve to a single DB call:
+//   findByOrganizationIdAndProviderAndStatus(orgId, 'jira_cloud', 'active')
+const schema = new SchemaBuilder(TaskManagementConnection, TaskManagementConnectionCollection)
+  // task_management_connections table has updated_at but no updated_by column. Suppress
+  // updatedBy so it is not included in INSERTs or UPDATEs.
+  .addAttribute('updatedBy', { type: 'string', required: false, postgrestIgnore: true })
+  .addReference('belongs_to', 'Organization', ['provider', 'status'])
+  .addReference('has_many', 'Tickets', ['updatedAt'], { removeDependents: true })
+  .addAttribute('provider', {
+    type: Object.values(TaskManagementConnection.PROVIDERS),
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('status', {
+    type: Object.values(TaskManagementConnection.STATUSES),
+    required: true,
+    default: TaskManagementConnection.STATUSES.ACTIVE,
+  })
+  // display_name column (PR #720): human-readable site name from Atlassian accessible-resources.
+  // Set by auth-service at OAuth callback time; updated on re-auth (user may reconnect to a
+  // different Jira site or Atlassian may rename the site). Not readOnly — setDisplayName() needed.
+  .addAttribute('displayName', {
+    type: 'string',
+    required: true,
+    validate: (value) => typeof value === 'string' && value.length > 0 && value.length <= 255,
+  })
+  // instance_url column (PR #720): Jira site URL (https://*.atlassian.net).
+  // Display-only — never used as a request target (SSRF protection: all outbound
+  // calls route through the fixed Atlassian gateway keyed on cloudId from metadata).
+  // Updated on re-auth — not readOnly so setInstanceUrl() works.
+  .addAttribute('instanceUrl', {
+    type: 'string',
+    required: true,
+    validate: (value) => isValidUrl(value),
+  })
+  // connected_by column (PR #720): IMS user ID (JWT sub) of the person who completed OAuth.
+  .addAttribute('connectedBy', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  // connected_at column: when OAuth was last successfully completed.
+  // Set on initial connect, updated on re-auth. Differs from createdAt after reconnect.
+  .addAttribute('connectedAt', {
+    type: 'string',
+    required: false,
+    validate: (value) => !value || isIsoDate(value),
+  })
+  // external_instance_id column: provider-stable identifier for the remote workspace.
+  // jira_cloud → Atlassian cloudId UUID; jira_corp → normalized baseUrl (v2).
+  // Used as the dedup key in UNIQUE(organization_id, provider, external_instance_id).
+  // Never changes after connection is created — readOnly.
+  .addAttribute('externalInstanceId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => typeof value === 'string' && value.length > 0,
+  })
+  .addAttribute('lastUsedAt', {
+    type: 'string',
+    required: false,
+    validate: (value) => !value || isIsoDate(value),
+  })
+  .addAttribute('errorMessage', {
+    type: 'string',
+    required: false,
+  })
+
+  // metadata JSONB (PR #720): provider-specific structured data.
+  // jira_cloud: { cloudId (required UUID), scopes (optional string array) }.
+  // siteName and siteUrl are NOT stored here — they live in displayName/instanceUrl above.
+  // No default — callers must supply valid metadata (e.g. { cloudId: '...' } for
+  // jira_cloud). An empty-object default would silently bypass validateMetadata's
+  // required-field check at the schema level.
+  .addAttribute('metadata', {
+    type: 'any',
+    required: true,
+    set: (value, allAttrs) => {
+      // Validate metadata on every write — defence-in-depth alongside DB CHECK constraint.
+      // The provider attribute is readOnly, so it's always present in allAttrs after creation.
+      const provider = allAttrs?.provider;
+      if (provider) {
+        validateMetadata(provider, value);
+      }
+      return value;
+    },
+  });
+
+export default schema.build();

package/src/models/ticket/index.d.ts

@@ -0,0 +1,40 @@
+/*
+ * 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, Opportunity, TaskManagementConnection, TicketSuggestion,
+} from '../index';
+
+export interface Ticket extends BaseModel {
+  getCreatedBy(): string;
+  getOpportunity(): Promise<Opportunity | null>;
+  getOpportunityId(): string | undefined;
+  getOrganization(): Promise<Organization>;
+  getOrganizationId(): string;
+  getTaskManagementConnection(): Promise<TaskManagementConnection>;
+  getTaskManagementConnectionId(): string;
+  getExternalTicketId(): string;
+  getTicketKey(): string;
+  getTicketProvider(): string;
+  getTicketStatus(): string;
+  getTicketSuggestions(): Promise<TicketSuggestion[]>;
+  getTicketUrl(): string;
+
+  setTicketStatus(status: string): Ticket;
+}
+
+export interface TicketCollection extends BaseCollection<Ticket> {
+  allByOrganizationId(organizationId: string): Promise<Ticket[]>;
+  allByTaskManagementConnectionId(connectionId: string): Promise<Ticket[]>;
+  findByOpportunityId(opportunityId: string): Promise<Ticket | null>;
+  findByOpportunityIdAndTicketKey(opportunityId: string, ticketKey: string): Promise<Ticket | null>;
+}

package/src/models/ticket/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 Ticket from './ticket.model.js';
+import TicketCollection from './ticket.collection.js';
+
+export {
+  Ticket,
+  TicketCollection,
+};

package/src/models/ticket/ticket.collection.js

@@ -0,0 +1,30 @@
+/*
+ * 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 BaseCollection from '../base/base.collection.js';
+
+/**
+ * TicketCollection — manages Ticket entities.
+ *
+ * Auto-generated index query methods (via schema GSIs):
+ *   allByOrganizationId(orgId)
+ *   allByTaskManagementConnectionId(connectionId)
+ *   findByOpportunityId(opportunityId)  — optional FK, nullable
+ *
+ * @class TicketCollection
+ * @extends BaseCollection
+ */
+class TicketCollection extends BaseCollection {
+  static COLLECTION_NAME = 'TicketCollection';
+}
+
+export default TicketCollection;