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

package/CHANGELOG.md

@@ -1,3 +1,19 @@
+## [@adobe/spacecat-shared-data-access-v4.0.0](https://github.com/adobe/spacecat-shared/compare/@adobe/spacecat-shared-data-access-v3.81.0...@adobe/spacecat-shared-data-access-v4.0.0) (2026-07-03)
+
+### ⚠ BREAKING CHANGES
+
+* **data-access:** drop startedAt/result/error from Preflight schema (SITES-47254) (#1740)
+
+### Features
+
+* **data-access:** drop startedAt/result/error from Preflight schema (SITES-47254) ([#1740](https://github.com/adobe/spacecat-shared/issues/1740)) ([5b728bb](https://github.com/adobe/spacecat-shared/commit/5b728bb623060289221e744088b9762a8acfe519)), closes [#2713](https://github.com/adobe/spacecat-shared/issues/2713) [#2713](https://github.com/adobe/spacecat-shared/issues/2713) [post-#2713](https://github.com/adobe/post-/issues/2713)
+
+## [@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

package/package.json

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

package/src/models/async-job/index.d.ts

@@ -12,6 +12,13 @@
 
 import type { BaseCollection, BaseModel } from '../base';
 
+// Note on nullable return types: `postgrest.utils.js::normalizeModelValue()`
+// maps DB NULL → JS `undefined` (the key is skipped on `this.record`
+// entirely), so auto-generated getters return `T | undefined` — never
+// `T | null` — for nullable columns. Callers checking `=== null` on these
+// will silently miss the unfinished-job branch. Existing declarations
+// that read `... | null` predate this PR; the lifecycle additions below
+// match the runtime contract.
 export interface AsyncJob extends BaseModel {
     getStatus(): string;
     getResultLocation(): string;
@@ -20,6 +27,8 @@ export interface AsyncJob extends BaseModel {
     getError(): { code: string; message: string; details?: object } | null;
     getMetadata(): object | null;
     getRecordExpiressAt(): number;
+    getStartedAt(): string | undefined;
+    getEndedAt(): string | undefined;
     setStatus(status: string): void;
     setResultLocation(location: string): void;
     setResultType(type: string): void;
@@ -27,6 +36,8 @@ export interface AsyncJob extends BaseModel {
     setError(error: { code: string; message: string; details?: object }): void;
     setMetadata(metadata: object): void;
     setExpiresAt(expiresAt: number): void;
+    setStartedAt(startedAt: string): void;
+    setEndedAt(endedAt: string): void;
 }
 
 export interface AsyncJobCollection extends BaseCollection<AsyncJob> {

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/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,
+};

package/src/models/index.d.ts

@@ -30,6 +30,8 @@ export type * from './import-url';
 export type * from './key-event';
 export type * from './latest-audit';
 export type * from './opportunity';
+export type * from './idempotency-key';
+export type * from './oauth-nonce';
 export type * from './organization';
 export type * from './page-citability';
 export type * from './page-intent';
@@ -40,6 +42,9 @@ export type * from './scrape-job';
 export type * from './scrape-url';
 export type * from './sentiment-guideline';
 export type * from './sentiment-topic';
+export type * from './task-management-connection';
+export type * from './ticket';
+export type * from './ticket-suggestion';
 export type * from './site';
 export type * from './site-candidate';
 export type * from './site-enrollment';

package/src/models/index.js

@@ -54,3 +54,8 @@ export * from './page-citability/index.js';
 export * from './plg-onboarding/index.js';
 export * from './sentiment-guideline/index.js';
 export * from './sentiment-topic/index.js';
+export * from './idempotency-key/index.js';
+export * from './oauth-nonce/index.js';
+export * from './task-management-connection/index.js';
+export * from './ticket/index.js';
+export * from './ticket-suggestion/index.js';

package/src/models/oauth-nonce/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 } from '../index';
+
+export interface OAuthNonce extends BaseModel {
+  getNonce(): string;
+  getExpiresAt(): string;
+}
+
+export interface OAuthNonceCollection extends BaseCollection<OAuthNonce> {
+  /**
+   * Atomically deletes a nonce by its value.
+   * Returns the number of rows deleted (1 = consumed, 0 = not found or already consumed).
+   */
+  delete(keys: { nonce: string }): Promise<number>;
+}

package/src/models/oauth-nonce/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 OAuthNonce from './oauth-nonce.model.js';
+import OAuthNonceCollection from './oauth-nonce.collection.js';
+
+export {
+  OAuthNonce,
+  OAuthNonceCollection,
+};

package/src/models/oauth-nonce/oauth-nonce.collection.js

@@ -0,0 +1,59 @@
+/*
+ * 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';
+
+/**
+ * OAuthNonceCollection — manages OAuthNonce records.
+ *
+ * @class OAuthNonceCollection
+ * @extends BaseCollection
+ */
+class OAuthNonceCollection extends BaseCollection {
+  static COLLECTION_NAME = 'OAuthNonceCollection';
+
+  /**
+   * Atomically consumes a nonce: deletes it only if it exists AND has not expired.
+   *
+   * Mirrors the intended DB operation from the migration:
+   *   DELETE FROM oauth_nonces WHERE nonce = $1 AND expires_at > NOW() RETURNING id
+   *
+   * Returns the number of rows deleted:
+   *   1 = consumed (nonce was valid and not expired)
+   *   0 = not found, already consumed, OR expired
+   *
+   * Used by auth-service to enforce single-use replay prevention at OAuth callback time.
+   * An expired nonce must return 0 (rejected) even if the row still exists in the DB —
+   * the background cleanup job may not have swept it yet.
+   *
+   * @param {object} keys
+   * @param {string} keys.nonce - The nonce value to consume.
+   * @returns {Promise<number>} 1 if the nonce was found and deleted, 0 otherwise.
+   */
+  async delete({ nonce } = {}) {
+    if (!nonce || typeof nonce !== 'string') {
+      throw new Error('nonce is required and must be a non-empty string');
+    }
+    const { data, error } = await this.postgrestService
+      .from(this.tableName)
+      .delete()
+      .eq('nonce', nonce)
+      .gt('expires_at', new Date().toISOString())
+      .select();
+    if (error) {
+      throw error;
+    }
+    return (data ?? []).length;
+  }
+}
+
+export default OAuthNonceCollection;

package/src/models/oauth-nonce/oauth-nonce.model.js

@@ -0,0 +1,35 @@
+/*
+ * 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';
+
+/**
+ * OAuthNonce — a single-use state token used for OAuth 2.0 CSRF/replay prevention.
+ *
+ * Lifecycle:
+ *   1. Created by auth-service at the start of an OAuth authorization flow.
+ *   2. Consumed atomically (via OAuthNonceCollection.delete) when the provider
+ *      redirects back to the callback endpoint.
+ *   3. If the nonce cannot be consumed the callback is rejected (replay attack).
+ *
+ * Rows are short-lived (TTL ≈ 10 minutes). A background cleanup job can sweep
+ * expired rows, but replay protection does not depend on cleanup — the nonce is
+ * deleted on first use regardless of expiresAt.
+ *
+ * @class OAuthNonce
+ * @extends BaseModel
+ */
+class OAuthNonce extends BaseModel {
+  static ENTITY_NAME = 'OAuthNonce';
+}
+
+export default OAuthNonce;

package/src/models/oauth-nonce/oauth-nonce.schema.js

@@ -0,0 +1,50 @@
+/*
+ * 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 OAuthNonce from './oauth-nonce.model.js';
+import OAuthNonceCollection from './oauth-nonce.collection.js';
+
+// nonce is the state parameter sent to the OAuth provider and consumed exactly once
+// at callback time to prevent CSRF/replay attacks. The index on nonce powers the
+// OAuthNonceCollection.delete({ nonce }) lookup used by auth-service at callback time.
+const schema = new SchemaBuilder(OAuthNonce, OAuthNonceCollection)
+  // oauth_nonces is append-only — the DB grants no UPDATE privilege (postgrest_anon and
+  // postgrest_writer both lack UPDATE). Disabling updates at the model layer surfaces a
+  // clean ValidationError instead of an opaque PostgREST 403 at the DB level.
+  .allowUpdates(false)
+  // oauth_nonces 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 })
+  .addAttribute('nonce', {
+    type: 'string',
+    required: true,
+    readOnly: true,
+  })
+  .addAttribute('expiresAt', {
+    type: 'string',
+    required: true,
+    validate: (value) => isIsoDate(value),
+  })
+  .addIndex(
+    { composite: ['nonce'] },
+    { composite: [] },
+  );
+
+export default schema.build();

package/src/models/organization/index.d.ts

@@ -11,7 +11,8 @@
  */
 
 import type {
-  BaseCollection, BaseModel, Site, Project, Entitlement, OrganizationIdentityProvider, TrialUser,
+  BaseCollection, BaseModel, Site, Project, Entitlement, OrganizationIdentityProvider,
+  TaskManagementConnection, TrialUser,
 } from '../index';
 
 export interface Organization extends BaseModel {
@@ -24,6 +25,7 @@ export interface Organization extends BaseModel {
   getProjects(): Promise<Project[]>;
   getEntitlements(): Promise<Entitlement[]>;
   getOrganizationIdentityProviders(): Promise<OrganizationIdentityProvider[]>;
+  getTaskManagementConnections(): Promise<TaskManagementConnection[]>;
   getTrialUsers(): Promise<TrialUser[]>;
   setConfig(config: object): Organization;
   setFulfillableItems(fulfillableItems: object): Organization;

package/src/models/organization/organization.schema.js

@@ -25,6 +25,7 @@ const schema = new SchemaBuilder(Organization, OrganizationCollection)
   .addReference('has_many', 'Projects')
   .addReference('has_many', 'Entitlements')
   .addReference('has_many', 'TrialUsers')
+  .addReference('has_many', 'TaskManagementConnections')
   .addAttribute('config', {
     type: 'any',
     required: true,

package/src/models/preflight/index.d.ts

@@ -12,6 +12,7 @@
 
 import type { AsyncJob, BaseCollection, BaseModel, Site } from '../index.js';
 
+// SITES-47254: startedAt/result/error live on AsyncJob — fetch via getAsyncJob().
 export interface Preflight extends BaseModel {
     getSiteId(): string;
     getSite(): Promise<Site>;
@@ -20,18 +21,14 @@ export interface Preflight extends BaseModel {
     getUrl(): string;
     getStatus(): string;
     getCreatedBy(): { email: string; displayName?: string };
-    getStartedAt(): string | null;
-    getEndedAt(): string | null;
-    getResult(): object | null;
-    getError(): { code: string; message: string } | null;
+    // `string | undefined` (not `| null`) because normalizeModelValue maps
+    // DB NULL → undefined on read — see AsyncJob/index.d.ts header.
+    getEndedAt(): string | undefined;
 
     setUrl(url: string): Preflight;
     setStatus(status: 'IN_PROGRESS' | 'COMPLETED' | 'FAILED' | 'CANCELLED'): Preflight;
     setCreatedBy(createdBy: { email: string; displayName?: string }): Preflight;
-    setStartedAt(startedAt: string): Preflight;
     setEndedAt(endedAt: string): Preflight;
-    setResult(result: object): Preflight;
-    setError(error: { code: string; message: string }): Preflight;
 }
 
 export interface PreflightCollection extends BaseCollection<Preflight> {