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

[prithipalpatwal]

Jira: SITES-44690

Summary

Adds five 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()

IdempotencyKey

• Deduplicates concurrent or retried requests using the Stripe idempotency pattern
• Status lifecycle: processing → completed | failed
• key and endpoint are readOnly (set at creation, never changed)
• updatedBy suppressed via postgrestIgnore (DB has no updated_by column)
• Collection: findActiveKey(key, orgId) filters by expires_at > NOW(), deleteExpired() sweeps expired rows

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 }) enforces expiry check (expires_at > NOW()) for atomic consume-on-use

🤖 Generated with Claude Code

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

[MysticatBot]

Hey @prithipalpatwal,

Verdict: Approve - IdempotencyKey model follows established patterns well; two minor TypeScript definition gaps noted.
Complexity: HIGH - large diff (2200+ lines, 42 files); database model schema with multiple entity relationships.
Changes: Adds TaskManagementConnection, Ticket, TicketSuggestion, IdempotencyKey, and OAuthNonce data models with status lifecycle, metadata validation, and cascade relationships (42 files).

Non-blocking (2): minor issues and suggestions

• suggestion: expiresAt is not marked readOnly in the schema, so BaseModel generates a setter, but setExpiresAt is absent from index.d.ts - either add readOnly: true (idempotency keys should not have their expiry extended post-creation) or add setExpiresAt(value: string): IdempotencyKey to the type definitions - idempotency-key/index.d.ts
• nit: getResponse() is typed as object | null but the schema declares type: 'any' - if the response payload is always a JSON object this is fine for the domain, but consider Record<string, unknown> | null or unknown for strict TS consumers - idempotency-key/index.d.ts

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: 0m 22s | Cost: $4.46 | Commit: 2a5e0dc27b52e5d06ee28cb36baa940ed39104de
If this code review was useful, please react with 👍. Otherwise, react with 👎.}

[MysticatBot]

Hey @prithipalpatwal,

Verdict: Approve - the readOnly fix and type tightening are correct; all prior blocking findings remain resolved.
Complexity: HIGH - large diff (2200+ lines, 42 files); database model schema with multiple entity relationships.
Changes: Marks IdempotencyKey.expiresAt as readOnly and tightens response type to Record<string, unknown> (3 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
• IdempotencyKey.expiresAt now marked readOnly (prevents expiry extension post-creation)
• Response type tightened to Record<string, unknown> | null (stricter than bare object)

---

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

[solaris007]

🎉 This PR is included in version @adobe/spacecat-shared-data-access-v3.81.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀