@adobe/spacecat-shared-data-access 3.79.1 → 3.81.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [@adobe/spacecat-shared-data-access-v3.81.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.80.0...@adobe/spacecat-shared-data-access-v3.81.0) (2026-07-02)
+
+### Features
+
+* **SITES-44690:** add TaskManagementConnection, Ticket, TicketSuggestion, IdempotencyKey, and OAuthNonce data models ([#1702](https://github.com/adobe/spacecat-shared/issues/1702)) ([2ca5096](https://github.com/adobe/spacecat-shared/commit/2ca5096b448a07b8e365021e06b31fa3bee96b09))
+
+## [@adobe/spacecat-shared-data-access-v3.80.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.79.1...@adobe/spacecat-shared-data-access-v3.80.0) (2026-07-02)
+
+### Features
+
+* **data-access:** add feedback review constants + verdict/signal helpers (SITES-43974) ([#1696](https://github.com/adobe/spacecat-shared/issues/1696)) ([2cabb05](https://github.com/adobe/spacecat-shared/commit/2cabb0596b27dcdefaf66c7d46531403ae005f2c))
+
 ## [@adobe/spacecat-shared-data-access-v3.79.1](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.79.0...@adobe/spacecat-shared-data-access-v3.79.1) (2026-06-22)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adobe/spacecat-shared-data-access",
-  "version": "3.79.1",
+  "version": "3.81.0",
   "description": "Shared modules of the Spacecat Services - Data Access",
   "type": "module",
   "engines": {

package/src/models/base/entity.registry.js

@@ -55,6 +55,11 @@ import SentimentGuidelineCollection from '../sentiment-guideline/sentiment-guide
 import SentimentTopicCollection from '../sentiment-topic/sentiment-topic.collection.js';
 import AccessGrantLogCollection from '../access-grant-log/access-grant-log.collection.js';
 import SiteImsOrgAccessCollection from '../site-ims-org-access/site-ims-org-access.collection.js';
+import IdempotencyKeyCollection from '../idempotency-key/idempotency-key.collection.js';
+import OAuthNonceCollection from '../oauth-nonce/oauth-nonce.collection.js';
+import TaskManagementConnectionCollection from '../task-management-connection/task-management-connection.collection.js';
+import TicketCollection from '../ticket/ticket.collection.js';
+import TicketSuggestionCollection from '../ticket-suggestion/ticket-suggestion.collection.js';
 
 import ApiKeySchema from '../api-key/api-key.schema.js';
 import AsyncJobSchema from '../async-job/async-job.schema.js';
@@ -97,6 +102,11 @@ import SentimentGuidelineSchema from '../sentiment-guideline/sentiment-guideline
 import SentimentTopicSchema from '../sentiment-topic/sentiment-topic.schema.js';
 import AccessGrantLogSchema from '../access-grant-log/access-grant-log.schema.js';
 import SiteImsOrgAccessSchema from '../site-ims-org-access/site-ims-org-access.schema.js';
+import IdempotencyKeySchema from '../idempotency-key/idempotency-key.schema.js';
+import OAuthNonceSchema from '../oauth-nonce/oauth-nonce.schema.js';
+import TaskManagementConnectionSchema from '../task-management-connection/task-management-connection.schema.js';
+import TicketSchema from '../ticket/ticket.schema.js';
+import TicketSuggestionSchema from '../ticket-suggestion/ticket-suggestion.schema.js';
 
 /**
  * EntityRegistry - A registry class responsible for managing entities, their schema and collection.
@@ -234,6 +244,11 @@ EntityRegistry.registerEntity(SentimentGuidelineSchema, SentimentGuidelineCollec
 EntityRegistry.registerEntity(SentimentTopicSchema, SentimentTopicCollection);
 EntityRegistry.registerEntity(AccessGrantLogSchema, AccessGrantLogCollection);
 EntityRegistry.registerEntity(SiteImsOrgAccessSchema, SiteImsOrgAccessCollection);
+EntityRegistry.registerEntity(IdempotencyKeySchema, IdempotencyKeyCollection);
+EntityRegistry.registerEntity(OAuthNonceSchema, OAuthNonceCollection);
+EntityRegistry.registerEntity(TaskManagementConnectionSchema, TaskManagementConnectionCollection);
+EntityRegistry.registerEntity(TicketSchema, TicketCollection);
+EntityRegistry.registerEntity(TicketSuggestionSchema, TicketSuggestionCollection);
 EntityRegistry.defaultEntities = { ...EntityRegistry.entities };
 
 export default EntityRegistry;

package/src/models/feedback-event/feedback-event.constants.js

@@ -0,0 +1,249 @@
+/*
+ * 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.
+ */
+
+/**
+ * @fileoverview Shared constants + helpers for the human-review feedback loop
+ * (SITES-43974). The `feedback_event` table has a client-supplied `event_id`
+ * primary key and is append-only, so it is NOT modelled as a data-access entity
+ * (the entity framework forces an auto-generated `id` PK). Producers and
+ * consumers — `spacecat-api-service` (capture + ?include=reviews composition)
+ * and `spacecat-jobs-dispatcher` (the daily JSONL exporter) — talk to the table
+ * via the raw `postgrestClient`. These constants + the verdict<->signal
+ * translation live here so the enum values and the JSONL contract never drift
+ * across those repos.
+ */
+
+/**
+ * Capture surface. Derived server-side from the API route (never trusted from
+ * the request body — FR-10). Only `backoffice` is wired up for v1; `aso_ui` and
+ * `aemy_pr` are reserved.
+ */
+export const REVIEW_SOURCES = Object.freeze({
+  BACKOFFICE: 'backoffice',
+  ASO_UI: 'aso_ui',
+  AEMY_PR: 'aemy_pr',
+});
+
+/**
+ * App-layer verdict — what the reviewer expresses in the UI / request body.
+ */
+export const REVIEW_VERDICTS = Object.freeze({
+  UP: 'up',
+  DOWN: 'down',
+});
+
+/**
+ * Persisted training label on `feedback_event.signal`. Translated once from the
+ * verdict at capture time (see {@link verdictToSignal}).
+ */
+export const REVIEW_SIGNALS = Object.freeze({
+  POSITIVE: 'positive',
+  NEGATIVE: 'negative',
+});
+
+/**
+ * Optional ESE category on a reject. `product_bug` rows are filtered OUT of the
+ * Learning Agent export (routed to Jira); `bad_recommendation` / `other` / NULL
+ * are exported.
+ */
+export const REJECTION_CATEGORIES = Object.freeze({
+  PRODUCT_BUG: 'product_bug',
+  BAD_RECOMMENDATION: 'bad_recommendation',
+  OTHER: 'other',
+});
+
+/**
+ * Commerce tier of the reviewed site at review time.
+ */
+export const FEEDBACK_TIERS = Object.freeze({
+  PAID: 'paid',
+  FREE: 'free',
+});
+
+/**
+ * Rejection categories whose rows must NOT be exported to the Learning Agent
+ * training corpus (they describe product/detection bugs the LA cannot learn
+ * from). The exporter filters these out; NULL-category rows are still exported.
+ */
+export const EXPORT_EXCLUDED_REJECTION_CATEGORIES = Object.freeze([
+  REJECTION_CATEGORIES.PRODUCT_BUG,
+]);
+
+/**
+ * Customer-derived fields stripped from the JSONL export for organizations with
+ * `training_opt_in = false`. Verdict / signal / category / identity metadata
+ * still ship. snake_case to match the JSONL row shape (and the feedback_event
+ * DB columns) — {@link toJsonlRow} uses this list to do the stripping, so the
+ * opt-out boundary is single-sourced here.
+ */
+export const OPT_OUT_STRIPPED_FIELDS = Object.freeze([
+  'previous_fix',
+  'edited_fix',
+  'detail_markdown',
+]);
+
+/**
+ * Current JSONL row schema version (the `schema_version` field stamped on every
+ * exported line). DMAI ignores unknown fields within a known version and SHOULD
+ * reject unknown versions; bump this in one place on a breaking change.
+ */
+export const SCHEMA_VERSION = 1;
+
+/**
+ * Translate the app-layer verdict to the persisted training signal. Single
+ * source of truth shared by the capture handler and any consumer.
+ *
+ * @param {string} verdict - one of {@link REVIEW_VERDICTS}.
+ * @returns {string} the corresponding {@link REVIEW_SIGNALS} value.
+ * @throws {Error} if the verdict is not a recognised value.
+ */
+export function verdictToSignal(verdict) {
+  if (verdict === REVIEW_VERDICTS.UP) {
+    return REVIEW_SIGNALS.POSITIVE;
+  }
+  if (verdict === REVIEW_VERDICTS.DOWN) {
+    return REVIEW_SIGNALS.NEGATIVE;
+  }
+  throw new Error(`Invalid review verdict: ${verdict}`);
+}
+
+/**
+ * Inverse of {@link verdictToSignal} — translate a persisted signal back to the
+ * app-layer verdict (used when composing reviews into an API response).
+ *
+ * @param {string} signal - one of {@link REVIEW_SIGNALS}.
+ * @returns {string} the corresponding {@link REVIEW_VERDICTS} value.
+ * @throws {Error} if the signal is not a recognised value.
+ */
+export function signalToVerdict(signal) {
+  if (signal === REVIEW_SIGNALS.POSITIVE) {
+    return REVIEW_VERDICTS.UP;
+  }
+  if (signal === REVIEW_SIGNALS.NEGATIVE) {
+    return REVIEW_VERDICTS.DOWN;
+  }
+  throw new Error(`Invalid review signal: ${signal}`);
+}
+
+/**
+ * Map a raw `feedback_event` row (snake_case, as returned by PostgREST) to the
+ * **API review view** (camelCase, verdict-flavoured) for HTTP responses — e.g.
+ * the `?include=reviews` composition in spacecat-api-service. This is NOT the
+ * JSONL export shape; use {@link toJsonlRow} for the Learning Agent export. The
+ * heavy patch fields (`previous_fix` / `edited_fix`) are omitted unless
+ * `includePatches` is set.
+ *
+ * @param {object} row - a raw feedback_event row from PostgREST.
+ * @param {object} [options]
+ * @param {boolean} [options.includePatches=false] - include previous/edited fix.
+ * @returns {object|null} the review view object, or null when no row is given.
+ */
+export function toReviewView(row, { includePatches = false } = {}) {
+  if (!row) {
+    return null;
+  }
+
+  const view = {
+    eventId: row.event_id,
+    eventTime: row.event_time,
+    source: row.source,
+    verdict: signalToVerdict(row.signal),
+    signal: row.signal,
+    reviewerId: row.reviewer_id ?? null,
+    detailMarkdown: row.detail_markdown ?? null,
+    rejectionCategory: row.rejection_category ?? null,
+    stateTransition: row.state_transition ?? null,
+    tier: row.tier,
+  };
+
+  if (includePatches) {
+    view.previousFix = row.previous_fix ?? null;
+    view.editedFix = row.edited_fix ?? null;
+  }
+
+  return view;
+}
+
+/**
+ * Whether a raw `feedback_event` row should be exported to the Learning Agent
+ * corpus. `product_bug` rejections are excluded (routed to Jira); NULL-category
+ * rows ARE exported. See {@link EXPORT_EXCLUDED_REJECTION_CATEGORIES}.
+ *
+ * @param {object} row - a raw feedback_event row from PostgREST.
+ * @returns {boolean} true if the row should be exported.
+ */
+export function shouldExport(row) {
+  return !EXPORT_EXCLUDED_REJECTION_CATEGORIES.includes(row.rejection_category);
+}
+
+/**
+ * Map a raw `feedback_event` row (snake_case, from PostgREST) to one JSONL line
+ * object — the canonical Learning Agent export contract. The row mirrors the
+ * feedback_event columns (snake_case), stamped with {@link SCHEMA_VERSION} and
+ * the derived `verdict`. For organizations that have NOT opted into training,
+ * the customer-derived fields in {@link OPT_OUT_STRIPPED_FIELDS} are nulled;
+ * verdict / signal / category / identity metadata still ship (§10.5.7).
+ *
+ * This is the single source of truth for the JSONL row shape — the exporter
+ * (spacecat-jobs-dispatcher) calls it rather than re-deriving the contract.
+ *
+ * @param {object} row - a raw feedback_event row from PostgREST.
+ * @param {object} [options]
+ * @param {boolean} [options.optedIn=false] - the org's training_opt_in.
+ * @returns {object} a single JSONL line object (snake_case).
+ */
+export function toJsonlRow(row, { optedIn = false } = {}) {
+  const jsonlRow = {
+    schema_version: SCHEMA_VERSION,
+    event_id: row.event_id,
+    event_time: row.event_time,
+    organization_id: row.organization_id,
+    site_id: row.site_id,
+    suggestion_id: row.suggestion_id,
+    opportunity_type: row.opportunity_type,
+    source: row.source,
+    signal: row.signal,
+    verdict: signalToVerdict(row.signal),
+    reviewer_id: row.reviewer_id ?? null,
+    rejection_category: row.rejection_category ?? null,
+    state_transition: row.state_transition ?? null,
+    tier: row.tier,
+    detail_markdown: row.detail_markdown ?? null,
+    previous_fix: row.previous_fix ?? null,
+    edited_fix: row.edited_fix ?? null,
+  };
+
+  if (!optedIn) {
+    OPT_OUT_STRIPPED_FIELDS.forEach((field) => {
+      jsonlRow[field] = null;
+    });
+  }
+
+  return jsonlRow;
+}
+
+/**
+ * Build the JSONL (newline-delimited JSON) export body from raw feedback_event
+ * rows: filters out non-exportable rows ({@link shouldExport}) and maps the rest
+ * through {@link toJsonlRow}.
+ *
+ * @param {Array<object>} rows - raw feedback_event rows from PostgREST.
+ * @param {object} [options]
+ * @param {boolean} [options.optedIn=false] - the org's training_opt_in.
+ * @returns {string} the JSONL body (no trailing newline).
+ */
+export function buildJsonl(rows, { optedIn = false } = {}) {
+  return rows
+    .filter(shouldExport)
+    .map((row) => JSON.stringify(toJsonlRow(row, { optedIn })))
+    .join('\n');
+}

package/src/models/feedback-event/index.d.ts

@@ -0,0 +1,85 @@
+/*
+ * 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.
+ */
+
+export const REVIEW_SOURCES: Readonly<{
+  BACKOFFICE: 'backoffice';
+  ASO_UI: 'aso_ui';
+  AEMY_PR: 'aemy_pr';
+}>;
+
+export const REVIEW_VERDICTS: Readonly<{ UP: 'up'; DOWN: 'down' }>;
+
+export const REVIEW_SIGNALS: Readonly<{ POSITIVE: 'positive'; NEGATIVE: 'negative' }>;
+
+export const REJECTION_CATEGORIES: Readonly<{
+  PRODUCT_BUG: 'product_bug';
+  BAD_RECOMMENDATION: 'bad_recommendation';
+  OTHER: 'other';
+}>;
+
+export const FEEDBACK_TIERS: Readonly<{ PAID: 'paid'; FREE: 'free' }>;
+
+export const EXPORT_EXCLUDED_REJECTION_CATEGORIES: ReadonlyArray<string>;
+
+/** snake_case JSONL/DB field names stripped from the export for opted-out orgs. */
+export const OPT_OUT_STRIPPED_FIELDS: ReadonlyArray<string>;
+
+/** Current JSONL row schema version stamped on every exported line. */
+export const SCHEMA_VERSION: number;
+
+/** Translate the app-layer verdict (`up`/`down`) to the persisted signal. */
+export function verdictToSignal(verdict: string): 'positive' | 'negative';
+
+/** Translate a persisted signal (`positive`/`negative`) back to the verdict. */
+export function signalToVerdict(signal: string): 'up' | 'down';
+
+export interface ReviewView {
+  eventId: string;
+  eventTime: string;
+  source: string;
+  verdict: 'up' | 'down';
+  signal: 'positive' | 'negative';
+  reviewerId: string | null;
+  detailMarkdown: string | null;
+  rejectionCategory: string | null;
+  stateTransition: string | null;
+  tier: string;
+  previousFix?: unknown;
+  editedFix?: unknown;
+}
+
+/**
+ * Map a raw PostgREST `feedback_event` row to the API review view (HTTP
+ * responses). Returns null when no row is given. NOT for JSONL export.
+ */
+export function toReviewView(
+  row: Record<string, unknown>,
+  options?: { includePatches?: boolean },
+): ReviewView | null;
+
+/** Whether a raw feedback_event row should be exported to the LA corpus. */
+export function shouldExport(row: Record<string, unknown>): boolean;
+
+/**
+ * Map a raw PostgREST `feedback_event` row to one JSONL export line (snake_case,
+ * schema_version-stamped). Customer-derived fields are nulled when optedIn=false.
+ */
+export function toJsonlRow(
+  row: Record<string, unknown>,
+  options?: { optedIn?: boolean },
+): Record<string, unknown>;
+
+/** Build the JSONL export body (filtered + mapped) from raw feedback_event rows. */
+export function buildJsonl(
+  rows: Array<Record<string, unknown>>,
+  options?: { optedIn?: boolean },
+): string;

package/src/models/feedback-event/index.js

@@ -0,0 +1,34 @@
+/*
+ * 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.
+ */
+
+// feedback_event has a client-supplied PK and is append-only, so it is NOT a
+// data-access entity (no model/collection/schema/registry). This barrel only
+// re-exports the shared constants + helpers consumed by spacecat-api-service
+// (capture + ?include=reviews) and spacecat-jobs-dispatcher (the JSONL exporter):
+// the enum vocabulary, the verdict<->signal translation, the API review view,
+// and the single-sourced JSONL row contract.
+export {
+  REVIEW_SOURCES,
+  REVIEW_VERDICTS,
+  REVIEW_SIGNALS,
+  REJECTION_CATEGORIES,
+  FEEDBACK_TIERS,
+  EXPORT_EXCLUDED_REJECTION_CATEGORIES,
+  OPT_OUT_STRIPPED_FIELDS,
+  SCHEMA_VERSION,
+  verdictToSignal,
+  signalToVerdict,
+  toReviewView,
+  shouldExport,
+  toJsonlRow,
+  buildJsonl,
+} from './feedback-event.constants.js';

package/src/models/idempotency-key/idempotency-key.collection.js

@@ -0,0 +1,89 @@
+/*
+ * 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 { hasText, isValidUUID } from '@adobe/spacecat-shared-utils';
+
+import { DataAccessError, ValidationError } from '../../errors/index.js';
+import BaseCollection from '../base/base.collection.js';
+
+/**
+ * IdempotencyKeyCollection — manages IdempotencyKey entities.
+ *
+ * Auto-generated index query methods (via schema references):
+ *   allByOrganizationId(organizationId) — all keys for an organization
+ *
+ * @class IdempotencyKeyCollection
+ * @extends BaseCollection
+ */
+class IdempotencyKeyCollection extends BaseCollection {
+  static COLLECTION_NAME = 'IdempotencyKeyCollection';
+
+  /**
+   * Finds a non-expired idempotency key by its value and organization.
+   *
+   * Returns null when:
+   *   - No key exists with that value for the organization
+   *   - The key exists but has expired (expires_at < NOW())
+   *
+   * @param {string} key - The idempotency key value.
+   * @param {string} organizationId - The organization UUID.
+   * @returns {Promise<import('./idempotency-key.model.js').default|null>}
+   */
+  async findActiveKey(key, organizationId) {
+    if (!hasText(key)) {
+      throw new ValidationError('key is required', this);
+    }
+    if (!isValidUUID(organizationId)) {
+      throw new ValidationError('organizationId must be a valid UUID', this);
+    }
+
+    const { data, error } = await this.postgrestService
+      .from(this.tableName)
+      .select()
+      .eq('key', key)
+      .eq('organization_id', organizationId)
+      .gt('expires_at', new Date().toISOString())
+      .limit(1);
+
+    if (error) {
+      throw new DataAccessError('Failed to find active idempotency key', { entityName: 'IdempotencyKey' }, error);
+    }
+
+    if (!data || data.length === 0) {
+      return null;
+    }
+
+    return this.createInstanceFromRow(data[0]);
+  }
+
+  /**
+   * Deletes all expired idempotency keys.
+   * Called by the cleanup scheduler (every 5 minutes).
+   *
+   * @returns {Promise<number>} Number of expired keys deleted.
+   */
+  async deleteExpired() {
+    const { data, error } = await this.postgrestService
+      .from(this.tableName)
+      .delete()
+      .lt('expires_at', new Date().toISOString())
+      .select('id');
+
+    if (error) {
+      throw new DataAccessError('Failed to delete expired idempotency keys', { entityName: 'IdempotencyKey' }, error);
+    }
+
+    return (data ?? []).length;
+  }
+}
+
+export default IdempotencyKeyCollection;

package/src/models/idempotency-key/idempotency-key.model.js

@@ -0,0 +1,41 @@
+/*
+ * 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';
+
+/**
+ * IdempotencyKey — deduplicates concurrent or retried requests using the
+ * Stripe idempotency pattern.
+ *
+ * Status lifecycle:
+ *   processing → completed   (cached success response)
+ *   processing → failed      (cached error response, client must generate new key to retry)
+ *
+ * Keys are scoped to (key, organizationId, endpoint) — cross-org collision is impossible
+ * and the same key can be used independently across different operations.
+ *
+ * Keys expire after 24 hours (or shorter for ephemeral locks like token refresh dedup).
+ *
+ * @class IdempotencyKey
+ * @extends BaseModel
+ */
+class IdempotencyKey extends BaseModel {
+  static ENTITY_NAME = 'IdempotencyKey';
+
+  static STATUSES = {
+    PROCESSING: 'processing',
+    COMPLETED: 'completed',
+    FAILED: 'failed',
+  };
+}
+
+export default IdempotencyKey;

package/src/models/idempotency-key/idempotency-key.schema.js

@@ -0,0 +1,51 @@
+/*
+ * 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 } from '@adobe/spacecat-shared-utils';
+
+import SchemaBuilder from '../base/schema.builder.js';
+import IdempotencyKey from './idempotency-key.model.js';
+import IdempotencyKeyCollection from './idempotency-key.collection.js';
+
+// idempotency_keys table has updated_at but no updated_by column.
+const schema = new SchemaBuilder(IdempotencyKey, IdempotencyKeyCollection)
+  .addAttribute('updatedBy', { type: 'string', required: false, postgrestIgnore: true })
+  .addReference('belongs_to', 'Organization')
+  .addAttribute('key', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('endpoint', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('status', {
+    type: Object.values(IdempotencyKey.STATUSES),
+    required: true,
+    default: IdempotencyKey.STATUSES.PROCESSING,
+  })
+  .addAttribute('response', {
+    type: 'any',
+    required: false,
+  })
+  .addAttribute('expiresAt', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+    validate: (value) => isIsoDate(value),
+  });
+
+export default schema.build();

package/src/models/idempotency-key/index.d.ts

@@ -0,0 +1,41 @@
+/*
+ * 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 } from '../index';
+
+export interface IdempotencyKey extends BaseModel {
+  getEndpoint(): string;
+  getExpiresAt(): string;
+  getKey(): string;
+  getOrganization(): Promise<Organization>;
+  getOrganizationId(): string;
+  getResponse(): Record<string, unknown> | null;
+  getStatus(): string;
+
+  setResponse(response: Record<string, unknown> | null): IdempotencyKey;
+  setStatus(status: string): IdempotencyKey;
+}
+
+export interface IdempotencyKeyCollection extends BaseCollection<IdempotencyKey> {
+  allByOrganizationId(organizationId: string): Promise<IdempotencyKey[]>;
+
+  /**
+   * Finds a non-expired idempotency key by its value and organization.
+   * Returns null when no active key exists.
+   */
+  findActiveKey(key: string, organizationId: string): Promise<IdempotencyKey | null>;
+
+  /**
+   * Deletes all expired idempotency keys. Returns the number deleted.
+   */
+  deleteExpired(): Promise<number>;
+}

package/src/models/idempotency-key/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 IdempotencyKey from './idempotency-key.model.js';
+import IdempotencyKeyCollection from './idempotency-key.collection.js';
+
+export {
+  IdempotencyKey,
+  IdempotencyKeyCollection,
+};