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

[prithipalpatwal]

Summary

Adds TaskManagementConnection, Ticket, and TicketSuggestion data models to spacecat-shared-data-access (SITES-44690). Aligned to mysticat-data-service PR #720 Postgres schema and solution doc.

TaskManagementConnection

• Represents an OAuth connection from an org to a task-management provider (e.g. Jira Cloud)
• Status lifecycle: active → disabled / requires_reauth / error → disconnected (soft-delete)
• Methods: isActive(), markRequiresReauth(), markDisabled(), markError(), markDisconnected()
• Schema attributes aligned with PR fix(deps): update dependency @adobe/spacecat-helix-content-sdk to v1.3.72 #720 NOT NULL columns: provider, status, displayName, instanceUrl, connectedBy, metadata
• metadata JSONB: { cloudId (required UUID), scopes (optional string[]) } — per PR fix(deps): update dependency @adobe/spacecat-helix-content-sdk to v1.3.72 #720; siteName/siteUrl are NOT in metadata, they live in displayName/instanceUrl columns
• validateMetadata() exported for use by auth-service on connection INSERT/UPDATE

Ticket

• Represents a Jira issue created by ASO via a TaskManagementConnection
• Stores ticketId (Jira internal numeric ID), ticketKey, ticketUrl, ticketStatus, ticketProvider (denormalized), createdBy (IMS user ID)
• Optional FK to Opportunity for single-suggestion queries without JOIN

TicketSuggestion

• M:N bridge between Suggestions and Tickets (1:1 enforced in v1 via UNIQUE(suggestion_id) at DB level)
• suggestionId is a logical TEXT reference — Suggestions live in DynamoDB, no Postgres FK
• GSI on suggestionId powers findBySuggestionId() to detect duplicate-ticket attempts

Merge order

1. mysticat-data-service #720 — SQL migrations (required first — integration tests pull mysticat-data-service Docker image)
2. spacecat-shared #1701 — spacecat-shared-ticket-client package
3. This PR — data models
4. spacecat-api-service #2661 — controller + routes

CI note

Integration tests (test:it) fail until mysticat-data-service PR #720 merges and a new Docker image is published. Unit tests pass (2405 passing, 100% coverage).

v1 scope deviations

Deviation	Reason	Path to v2
STATUSES.DISCONNECTED added (not in spec)	Soft-delete preserves audit history	GC job hard-deletes disconnected rows in v2
lastUsedAt / errorMessage not in schema	Nullable columns; owned by auth-service connection management PR	Add attributes when auth-service PR lands
status_synced_at not in Ticket schema	Webhook status sync is a v2 feature	Add attribute when v2 ships

Related

• mysticat-data-service #720 — SQL migrations (5 tables)
• spacecat-shared #1701 — spacecat-shared-ticket-client
• spacecat-infrastructure #637 — SM IAM policy
• spacecat-api-service #2661 — controller + routes
• SITES-44690

[github-actions]

This PR will trigger a minor release when merged.

[MysticatBot]

Hey @prithipalpatwal,

Verdict: Request changes - four structural issues to address before merge; the code quality and patterns are solid otherwise.
Complexity: HIGH - large diff (1300+ lines, 22 files); database model schema with multiple entity relationships.
Changes: Adds TaskManagementConnection, Ticket, and TicketSuggestion data models with status lifecycle, metadata validation, and cascade relationships (22 files).
Note: CI checks are currently failing - expected per PR body (integration tests require mysticat-data-service PR #720).

Must fix before merge

1. [Important] Ticket schema missing has_many TicketSuggestions with removeDependents: true - orphan records on cascade delete - ticket/ticket.schema.js (details inline)
2. [Important] jira_corp metadata schema defined but unreachable through model layer - metadata-validator.js / task-management-connection.model.js (details inline)
3. [Important] validateMetadata not wired into schema validation - invalid metadata can reach DB - task-management-connection.schema.js (details inline)
4. [Important] metadata attribute default: {} conflicts with provider validation contracts - task-management-connection.schema.js (details inline)

Non-blocking (5): minor issues and suggestions

• nit: instanceUrl uses weak startsWith('https://') check while ticketUrl uses the stronger isValidUrl() from shared-utils - inconsistent validation strength - task-management-connection.schema.js
• nit: Ticket.DEFAULT_STATUS = 'To Do' uses a display-label string with spaces while all other status enums use snake_case identifiers - ticket/ticket.model.js:6
• suggestion: ticketProvider on Ticket is unconstrained string while provider on TaskManagementConnection uses enum validation - consider type: Object.values(TaskManagementConnection.PROVIDERS) - ticket/ticket.schema.js
• suggestion: scopes array in metadata validator has no length limit on the array or individual strings - add reasonable bounds - metadata-validator.js
• suggestion: Consider adding markActive() convenience method for the re-auth reconnection flow - task-management-connection.model.js

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 2m 42s | Cost: $8.82 | Commit: 1eadf949525929b3f5f245daf2e448bc4df71106
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[MysticatBot]

issue (blocking): The TicketSuggestion schema declares belongs_to Ticket, creating a FK relationship. However, this Ticket schema does not declare has_many TicketSuggestions with removeDependents: true. When a Ticket is deleted (via TaskManagementConnection cascade), TicketSuggestion records will be orphaned.

The cascade path is: Connection removal -> Tickets deleted -> TicketSuggestion rows left dangling. findBySuggestionId() would then return a TicketSuggestion whose getTicket() fails or returns null, making it appear a suggestion was ticketed when the ticket no longer exists.

Fix: Add .addReference('has_many', 'TicketSuggestions', ['createdAt'], { removeDependents: true }) to this schema.

[MysticatBot]

issue (blocking): The jira_corp metadata schema here is architecturally unreachable. The provider attribute in the connection schema constrains valid values to Object.values(TaskManagementConnection.PROVIDERS) which is only ['jira_cloud']. A record with provider: 'jira_corp' cannot be created through the model path.

This creates dead code that implies runtime coverage of a path that cannot execute. It will confuse the next engineer who touches this.

Fix: Either (a) remove the jira_corp entry and its tests until PROVIDERS is extended, or (b) add JIRA_CORP: 'jira_corp' to PROVIDERS now if it is genuinely needed for the auth-service pre-validation path (and document that the validator is called independently of the model layer).

[MysticatBot]

issue (blocking): The metadata attribute uses type: 'any' with no validate callback. The exported validateMetadata() is never called from within the model/schema layer, meaning a TaskManagementConnection can be persisted with arbitrary metadata that violates the provider contract.

The current design relies on caller discipline with zero enforcement at the data layer. One missed call site and invalid metadata reaches the DB.

Fix: Override save() in the model to call validateMetadata(this.getProvider(), this.getMetadata()) before persisting. This follows the pattern used by other models in this codebase for co-presence invariants. Alternatively, wire it into the schema validate callback if the framework supports cross-field access.

[MysticatBot]

issue (blocking): The default: {} on metadata conflicts with the validation contract. For jira_cloud, an empty object is invalid (missing required cloudId). If a connection is ever created relying on this default, it will pass schema validation but silently store invalid state.

Since required: true already prevents null/undefined, the default serves no purpose other than masking an omission that should be a hard error.

Fix: Remove default: {} so that omitting metadata triggers a validation failure at creation time.

[MysticatBot]

Hey @prithipalpatwal,

Verdict: Request changes - four data-integrity and validation issues remain unaddressed since the prior review, plus one newly identified cascade gap.
Complexity: HIGH - large diff (1300+ lines, 22 files); database model schema with multiple entity relationships.
Changes: Adds TaskManagementConnection, Ticket, and TicketSuggestion data models with status lifecycle, metadata validation, and cascade relationships (22 files).
Note: CI checks are currently failing - expected per PR body (integration tests require mysticat-data-service PR #720).

Must fix before merge

1. [Important] Ticket schema missing has_many TicketSuggestions with removeDependents: true - orphan records on cascade delete - ticket/ticket.schema.js:20 (details inline)
2. [Important] Organization schema missing has_many TaskManagementConnections - cascade from org deletion will orphan connections and their child tickets - organization/organization.schema.js (not in diff - one-line addition needed: .addReference('has_many', 'TaskManagementConnections', ['updatedAt'], { removeDependents: true }) following the existing Sites/Projects/Entitlements pattern)
3. [Important] instanceUrl uses weak startsWith('https://') while sibling ticketUrl uses isValidUrl() from shared-utils - inconsistent validation strength - task-management-connection.schema.js:48 (details inline)
4. [Important] metadata attribute default: {} conflicts with validateMetadata('jira_cloud', {}) which requires cloudId - creates schema-valid but business-invalid state - task-management-connection.schema.js:60 (details inline)

Non-blocking (5): minor issues and suggestions

• nit: jira_corp metadata schema in metadata-validator.js is unreachable through model layer (PROVIDERS enum only has jira_cloud) - add a comment noting it is forward-looking, or remove until PROVIDERS is extended
• suggestion: Wire validateMetadata into the schema validate callback or add a prominent JSDoc on the metadata attribute noting that callers MUST call it externally - the current implicit contract is invisible to future contributors - task-management-connection.schema.js:57
• nit: scopes array in metadata validator has no length limit on the array or individual strings - add reasonable bounds (e.g., max 100 entries, max 256 chars each) - metadata-validator.js:48
• nit: validateMetadata does not guard against non-object input (null/undefined/string) - will throw TypeError instead of clean ValidationError - metadata-validator.js:73
• suggestion: Add the 3 new entities to the README's "Current exported entities" list - packages/spacecat-shared-data-access/README.md

---

_{Skill: pr-review | Model: us.anthropic.claude-opus-4-6-v1[1m] | Duration: 3m 3s | Cost: $8.14 | Commit: 9b00cf55343c95dd6c9bc628a44fb8c76b584255
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[MysticatBot]

issue (blocking): The cascade chain is incomplete. TaskManagementConnection correctly declares has_many Tickets with removeDependents: true, but this Ticket schema has no corresponding has_many TicketSuggestions. When a Ticket is deleted (via Connection cascade), TicketSuggestion rows are orphaned. The findBySuggestionId() GSI will then return bridge records pointing at deleted tickets, making it appear a suggestion is still ticketed.

The Opportunity schema in this codebase uses the identical pattern: .addReference("has_many", "Suggestions", ["updatedAt"], { removeDependents: true }).

Fix: Add .addReference('has_many', 'TicketSuggestions', ['updatedAt'], { removeDependents: true }) to this schema.

[MysticatBot]

issue (blocking): instanceUrl validates with value.startsWith("https://") which accepts malformed values like https://, https:// , or strings with control characters. The Ticket schema uses the stricter isValidUrl() from @adobe/spacecat-shared-utils for ticketUrl. Since instanceUrl is stored permanently and rendered in UIs, it should use the same validation.

Fix:

import { isValidUrl } from '@adobe/spacecat-shared-utils';
// ...
validate: (value) => isValidUrl(value),

[MysticatBot]

issue (blocking): metadata has default: {} but validateMetadata('jira_cloud', {}) throws because cloudId is required. Since required: true already ensures callers must provide the field, this default only fires when metadata is omitted - creating a record that passes schema validation but violates the business invariant. Any reader trusting metadata.cloudId on such a record will encounter undefined.

Fix: Remove default: {}. The required: true constraint already enforces that callers provide metadata explicitly.