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

[prithipalpatwal]

Jira: SITES-44690

Summary

Adds four data models to spacecat-shared-data-access for the Jira integration feature (SITES-44690).

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(), markActive(), markRequiresReauth(), markDisabled(), markError(),
  markDisconnected()
• displayName and instanceUrl are mutable (updated on re-auth by auth-service)
• metadata JSONB: { cloudId (required UUID), scopes (optional string[]) } — validated by validateMetadata()
• updatedBy suppressed via postgrestIgnore (DB has no updated_by column)
• Collection: findActiveByOrganizationAndProvider(orgId, provider)

Ticket

• Represents a Jira issue created by ASO via a TaskManagementConnection
• taskManagementConnectionId → postgrestField: 'connection_id' (DB column name override)
• Stores externalTicketId, ticketKey, ticketUrl, ticketStatus, ticketProvider, createdBy
• Optional FK to Opportunity for single-suggestion queries without JOIN
• updatedBy suppressed via postgrestIgnore (DB has no updated_by column)

TicketSuggestion

• M:N bridge between Suggestions and Tickets (1:1 enforced in v1 via UNIQUE(suggestion_id) at DB level)
• Append-only: allowUpdates(false) — DB grants no UPDATE privilege
• updatedAt/updatedBy suppressed via postgrestIgnore (append-only, no DB columns)
• GSI on suggestionId powers findBySuggestionId()

OAuthNonce

• Single-use nonce store for HMAC-signed OAuth state token replay prevention
• Append-only: allowUpdates(false) — no UPDATE privilege
• updatedAt/updatedBy suppressed via postgrestIgnore (append-only, no DB columns)
• Custom delete({ nonce }) for atomic consume-on-use pattern

Test coverage

2468 passing, 100% lines/statements, 97%+ branches per package.

[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.

[MysticatBot]

Hey @prithipalpatwal,

Verdict: Request changes - two input-validation gaps in security-sensitive paths; otherwise ready to ship.
Complexity: HIGH - large diff (34 files); database model schema with multiple entity relationships.
Changes: Adds TaskManagementConnection, Ticket, TicketSuggestion, and OAuthNonce data models with status lifecycle, metadata validation, and cascade relationships (34 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] validateMetadata throws TypeError on non-object input instead of ValidationError - metadata-validator.js:78 (details inline)
2. [Important] OAuthNonceCollection.delete() has no guard against undefined/null nonce - oauth-nonce.collection.js:33 (details inline)

Non-blocking (3): minor issues and suggestions

• suggestion: scopes array in metadata validator has no length limit - add a reasonable cap (e.g., 100 entries) to prevent JSONB bloat from a malformed OAuth response - metadata-validator.js:61
• suggestion: ticketProvider on Ticket is an unconstrained string while provider on TaskManagementConnection uses enum validation - consider type: Object.values(TaskManagementConnection.PROVIDERS) for consistency - ticket.schema.js:51
• nit: Copyright year is 2024 in all new files created in 2025/2026

Previously flagged, now resolved

• Ticket schema now has has_many TicketSuggestions with removeDependents: true
• Organization schema now has has_many TaskManagementConnections
• instanceUrl now validates with isValidUrl() (consistent with ticketUrl)
• metadata attribute is required: true with no default (no conflict with validateMetadata contracts)

---

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

[MysticatBot]

issue (blocking): validateMetadata does not guard against non-object input. When metadata is null, undefined, a string, or a number, the function throws a TypeError (from metadata[field] access or Object.keys(metadata)) instead of a clean ValidationError.

Since this function is exported and called by auth-service on INSERT/UPDATE, a malformed request body will surface as an unhandled TypeError rather than a catchable validation rejection.

Fix:

// At the top of validateMetadata(), before the schema lookup:
if (metadata == null || typeof metadata !== 'object' || Array.isArray(metadata)) {
  throw new ValidationError('metadata must be a non-null object');
}

[MysticatBot]

issue (blocking): delete({ nonce } = {}) passes nonce to .eq('nonce', nonce) without validating it. Calling delete() or delete({}) sends undefined to PostgREST, which may produce undefined query behavior (matching NULL rows or an opaque API error).

The same PR establishes the pattern in TaskManagementConnectionCollection.findActiveByOrganizationAndProvider() where inputs are validated before use. Apply the same discipline here:

async delete({ nonce } = {}) {
  if (!nonce) {
    throw new ValidationError('nonce is required');
  }
  // ... rest unchanged
}

[MysticatBot]

Hey @prithipalpatwal,

Verdict: Request changes - one data-integrity gap in OAuthNonce expiry enforcement at consume time.
Complexity: HIGH - large diff (2200+ lines, 36 files); database model schema with multiple entity relationships.
Changes: Adds TaskManagementConnection, Ticket, TicketSuggestion, and OAuthNonce data models with status lifecycle, metadata validation, and cascade relationships (36 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] OAuthNonce delete() does not enforce expiry - expired nonces can still be consumed successfully - oauth-nonce.collection.js:34 (details inline)

Non-blocking (3): minor issues and suggestions

• suggestion: ticketProvider on Ticket is an unconstrained string while provider on TaskManagementConnection uses enum validation - consider constraining with type: Object.values(TaskManagementConnection.PROVIDERS) for consistency - ticket.schema.js:51
• suggestion: scopes array in metadata validator has no length limit on the array or individual strings - add reasonable bounds to prevent JSONB bloat - metadata-validator.js:48
• nit: suggestionId and opportunityId on TicketSuggestion have no format validation (e.g. minimum length or UUID check) - low risk since fields are readOnly but would prevent empty-ish values - ticket-suggestion.schema.js:14

Previously flagged, now resolved

• Ticket schema now has has_many TicketSuggestions with removeDependents: true
• Organization schema now has has_many TaskManagementConnections
• instanceUrl now validates with isValidUrl() (consistent with ticketUrl)
• metadata attribute is required: true with no default (no conflict with validateMetadata contracts)
• validateMetadata wired into schema via set hook on metadata attribute
• validateMetadata guards against non-object input (null, array, string)
• OAuthNonceCollection.delete() validates nonce input before query

---

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

[MysticatBot]

issue (blocking): The delete() method consumes a nonce without checking expires_at. The mysticat-data-service migration (PR #720) documents the intended consume pattern as:

DELETE FROM oauth_nonces WHERE nonce = $1 AND expires_at > NOW() RETURNING id

The current implementation only does .delete().eq("nonce", nonce).select() without an expiry filter. This means an expired nonce that has not yet been swept by the cleanup job can still be consumed successfully, returning 1 to the caller. The auth-service would then proceed with the OAuth callback despite the state token being outside its validity window.

The 10-minute TTL is a security control (limits replay window), not just a space-management hint. Without enforcement at consume time, the nonce TTL is advisory.

Fix: Add an expiry filter to the PostgREST chain:

const { data, error } = await this.postgrestService
  .from(this.tableName)
  .delete()
  .eq('nonce', nonce)
  .gt('expires_at', new Date().toISOString())
  .select();

This ensures expired nonces are rejected at consume time regardless of cleanup job timing.

[MysticatBot]

Hey @prithipalpatwal,

Verdict: Approve - the expiry enforcement fix is correct; all prior blocking findings resolved.
Complexity: HIGH - large diff (2200+ lines, 36 files); database model schema with multiple entity relationships.
Changes: Adds TaskManagementConnection, Ticket, TicketSuggestion, and OAuthNonce data models with status lifecycle, metadata validation, and cascade relationships (36 files).

Previously flagged, now resolved

• OAuthNonce delete() now enforces expiry via .gt('expires_at', now) - expired nonces return 0 (rejected)
• Ticket schema has has_many TicketSuggestions with removeDependents: true
• Organization schema has has_many TaskManagementConnections
• instanceUrl validates with isValidUrl() (consistent with ticketUrl)
• metadata is required: true with no default (no conflict with validateMetadata contracts)
• validateMetadata wired into schema via set hook on metadata attribute
• validateMetadata guards against non-object input (null, array, string)
• OAuthNonceCollection.delete() validates nonce input before query

---

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