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

package/src/models/ticket/ticket.model.js

@@ -0,0 +1,44 @@
+/*
+ * 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';
+
+/**
+ * Ticket — one Jira issue created by ASO via a TaskManagementConnection.
+ *
+ * Preserves the provider-side identifiers needed for future operations:
+ *   externalTicketId — Jira's internal numeric ID (data.id). Required for PATCH/update calls.
+ *   ticketKey      — Human-readable issue key, e.g. 'ASO-42'. Used in UI links.
+ *   ticketUrl      — Direct browser URL, e.g. 'https://acme.atlassian.net/browse/ASO-42'.
+ *   ticketProvider — Provider that created the ticket (e.g. 'jira_cloud'). Denormalized from
+ *                    the connection so the audit record is self-contained even if the connection
+ *                    is later deleted.
+ *   createdBy      — IMS user ID of the person who initiated ticket creation (JWT sub claim).
+ *
+ * ticketStatus mirrors the Jira column heading ('To Do', 'In Progress', 'Done').
+ * It is updated asynchronously by a future status-sync job (v2); write directly via
+ * setTicketStatus() + save() only from that job.
+ *
+ * v1 scope — intentional deviations from the architecture spec:
+ *   - No status_synced_at: Jira webhook status sync is a v2 feature. UI links to ticketUrl
+ *     for live status.
+ *   - opportunityId is kept as an optional FK on Ticket in addition to the TicketSuggestion
+ *     bridge so single-suggestion queries don't require a JOIN.
+ *
+ * @class Ticket
+ * @extends BaseModel
+ */
+class Ticket extends BaseModel {
+  static ENTITY_NAME = 'Ticket';
+}
+
+export default Ticket;

package/src/models/ticket/ticket.schema.js

@@ -0,0 +1,72 @@
+/*
+ * 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 { isValidUUID, isValidUrl } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import Ticket from './ticket.model.js';
+import TicketCollection from './ticket.collection.js';
+
+const schema = new SchemaBuilder(Ticket, TicketCollection)
+  // tickets table has updated_at but no updated_by column. Suppress updatedBy so
+  // it is not included in INSERTs.
+  .addAttribute('updatedBy', { type: 'string', required: false, postgrestIgnore: true })
+  .addReference('belongs_to', 'Organization')
+  .addReference('belongs_to', 'TaskManagementConnection')
+  // The DB column for the TaskManagementConnection FK is `connection_id` (not
+  // `task_management_connection_id`). Override the auto-generated attribute to
+  // point to the correct column so PostgREST queries and INSERTs use the right name.
+  .addAttribute('taskManagementConnectionId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    postgrestField: 'connection_id',
+    validate: (value) => isValidUUID(value),
+  })
+  // Optional FK — a ticket may not be linked to an opportunity in future flows.
+  .addReference('belongs_to', 'Opportunity', ['ticketKey'], { required: false })
+  .addReference('has_many', 'TicketSuggestions', ['createdAt'], { removeDependents: true })
+  .addAttribute('externalTicketId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('ticketKey', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('ticketUrl', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isValidUrl(value),
+  })
+  .addAttribute('ticketStatus', {
+    type: 'string',
+    required: false,
+    default: null,
+  })
+  .addAttribute('ticketProvider', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('createdBy', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  });
+
+export default schema.build();

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

@@ -0,0 +1,26 @@
+/*
+ * 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, Ticket } from '../index';
+
+export interface TicketSuggestion extends BaseModel {
+  getCreatedBy(): string;
+  getOpportunityId(): string | undefined;
+  getSuggestionId(): string;
+  getTicketId(): string;
+  getTicket(): Promise<Ticket>;
+}
+
+export interface TicketSuggestionCollection extends BaseCollection<TicketSuggestion> {
+  allByTicketId(ticketId: string): Promise<TicketSuggestion[]>;
+  findBySuggestionId(suggestionId: string): Promise<TicketSuggestion | null>;
+}

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

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

@@ -0,0 +1,29 @@
+/*
+ * 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';
+
+/**
+ * TicketSuggestionCollection — manages TicketSuggestion bridge records.
+ *
+ * Auto-generated query methods (via schema references and indexes):
+ *   allByTicketId(ticketId)               — all suggestions linked to a ticket
+ *   findBySuggestionId(suggestionId)      — look up whether a suggestion has been ticketed
+ *
+ * @class TicketSuggestionCollection
+ * @extends BaseCollection
+ */
+class TicketSuggestionCollection extends BaseCollection {
+  static COLLECTION_NAME = 'TicketSuggestionCollection';
+}
+
+export default TicketSuggestionCollection;

package/src/models/ticket-suggestion/ticket-suggestion.model.js

@@ -0,0 +1,36 @@
+/*
+ * 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';
+
+/**
+ * TicketSuggestion — bridge record linking a Suggestion to the Ticket created for it.
+ *
+ * Enforces 1:1 in v1: `UNIQUE (suggestion_id)` at the DB level prevents the same
+ * suggestion from being ticketed twice. In v2, the constraint relaxes to
+ * `UNIQUE (suggestion_id, ticket_id)` to support grouped ticket creation (M:N).
+ *
+ * `suggestionId` is a logical reference (stored as TEXT), not a Postgres FK.
+ * Suggestions live in DynamoDB/ElectroDB — there is no Postgres FK to enforce.
+ * Application-layer validation ensures the suggestion exists before creating this record.
+ *
+ * `opportunityId` is stored for direct opportunity-scoped queries without requiring
+ * a JOIN through the Ticket row.
+ *
+ * @class TicketSuggestion
+ * @extends BaseModel
+ */
+class TicketSuggestion extends BaseModel {
+  static ENTITY_NAME = 'TicketSuggestion';
+}
+
+export default TicketSuggestion;

package/src/models/ticket-suggestion/ticket-suggestion.schema.js

@@ -0,0 +1,53 @@
+/*
+ * 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 SchemaBuilder from '../base/schema.builder.js';
+import TicketSuggestion from './ticket-suggestion.model.js';
+import TicketSuggestionCollection from './ticket-suggestion.collection.js';
+
+// GSI on suggestionId powers findBySuggestionId() — used to check if a
+// suggestion has already been ticketed before attempting to create a duplicate.
+const schema = new SchemaBuilder(TicketSuggestion, TicketSuggestionCollection)
+  // ticket_suggestions is append-only — the DB grants no UPDATE privilege (bridge rows are
+  // immutable once created; delete and recreate if wrong). Disabling updates at the model
+  // layer surfaces a clean ValidationError instead of an opaque PostgREST 403.
+  .allowUpdates(false)
+  // ticket_suggestions is append-only — no updated_at or updated_by columns in the DB.
+  // Suppress the SchemaBuilder auto-added attributes so they are not included in INSERTs.
+  .addAttribute('updatedAt', {
+    type: 'string', required: false, readOnly: true, postgrestIgnore: true,
+  })
+  .addAttribute('updatedBy', { type: 'string', required: false, postgrestIgnore: true })
+  .addReference('belongs_to', 'Ticket')
+  .addAttribute('suggestionId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('opportunityId', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('createdBy', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addIndex(
+    { composite: ['suggestionId'] },
+    { composite: [] },
+  );
+
+export default schema.build();

package/src/service/index.d.ts

@@ -44,6 +44,11 @@ import type { SiteEnrollmentCollection } from '../models/site-enrollment';
 import type { SiteTopFormCollection } from '../models/site-top-form';
 import type { SiteTopPageCollection } from '../models/site-top-page';
 import type { SuggestionCollection } from '../models/suggestion';
+import type { IdempotencyKeyCollection } from '../models/idempotency-key';
+import type { OAuthNonceCollection } from '../models/oauth-nonce';
+import type { TaskManagementConnectionCollection } from '../models/task-management-connection';
+import type { TicketCollection } from '../models/ticket';
+import type { TicketSuggestionCollection } from '../models/ticket-suggestion';
 import type { TrialUserCollection } from '../models/trial-user';
 import type { TrialUserActivityCollection } from '../models/trial-user-activity';
 
@@ -94,6 +99,11 @@ export interface DataAccess {
   SiteTopForm: SiteTopFormCollection;
   SiteTopPage: SiteTopPageCollection;
   Suggestion: SuggestionCollection;
+  IdempotencyKey: IdempotencyKeyCollection;
+  OAuthNonce: OAuthNonceCollection;
+  TaskManagementConnection: TaskManagementConnectionCollection;
+  Ticket: TicketCollection;
+  TicketSuggestion: TicketSuggestionCollection;
   TrialUser: TrialUserCollection;
   TrialUserActivity: TrialUserActivityCollection;
 }