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

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

@@ -26,6 +26,7 @@ export * from './geo-experiment/index.js';
 export * from './fix-entity/index.js';
 export * from './fix-entity-suggestion/index.js';
 export * from './experiment/index.js';
+export * from './feedback-event/index.js';
 export * from './import-job/index.js';
 export * from './import-url/index.js';
 export * from './key-event/index.js';
@@ -53,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/task-management-connection/index.d.ts

@@ -0,0 +1,82 @@
+/*
+ * 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, Ticket,
+} from '../index';
+
+export interface TaskManagementConnection extends BaseModel {
+  /** Returns true when the connection is healthy and ready to create tickets. */
+  isActive(): boolean;
+  /**
+   * Persists status = 'requires_reauth'. Call this after a failed token refresh
+   * so the UI can prompt the user to reconnect.
+   */
+  markRequiresReauth(): Promise<TaskManagementConnection>;
+  /** Persists status = 'disabled'. */
+  markDisabled(): Promise<TaskManagementConnection>;
+  /** Persists status = 'error' after repeated API failures. */
+  markError(): Promise<TaskManagementConnection>;
+  /** Persists status = 'active' after a successful re-authorization. */
+  markActive(): Promise<TaskManagementConnection>;
+  /** Persists status = 'disconnected' (soft-delete on user revoke). */
+  markDisconnected(): Promise<TaskManagementConnection>;
+
+  getConnectedAt(): string | null;
+  getConnectedBy(): string;
+  getDisplayName(): string;
+  getErrorMessage(): string | null;
+  getExternalInstanceId(): string;
+  getInstanceUrl(): string;
+  getLastUsedAt(): string | null;
+  getMetadata(): object;
+  getOrganization(): Promise<Organization>;
+  getOrganizationId(): string;
+  getProvider(): string;
+  getStatus(): string;
+  getTickets(): Promise<Ticket[]>;
+
+  setConnectedAt(timestamp: string): TaskManagementConnection;
+  setDisplayName(name: string): TaskManagementConnection;
+  setErrorMessage(message: string | null): TaskManagementConnection;
+  setInstanceUrl(url: string): TaskManagementConnection;
+  setLastUsedAt(timestamp: string): TaskManagementConnection;
+  setMetadata(metadata: object): TaskManagementConnection;
+  setStatus(status: string): TaskManagementConnection;
+}
+
+export interface TaskManagementConnectionCollection extends BaseCollection<TaskManagementConnection> {
+  /**
+   * Returns the active connection for an org + provider pair used by the
+   * ticket-creation API before every ticket request, or null if none exists.
+   */
+  findActiveByOrganizationAndProvider(
+    organizationId: string,
+    provider: string,
+  ): Promise<TaskManagementConnection | null>;
+
+  allByOrganizationId(organizationId: string): Promise<TaskManagementConnection[]>;
+  allByOrganizationIdAndProvider(
+    organizationId: string,
+    provider: string,
+  ): Promise<TaskManagementConnection[]>;
+  allByOrganizationIdAndProviderAndStatus(
+    organizationId: string,
+    provider: string,
+    status: string,
+  ): Promise<TaskManagementConnection[]>;
+  findByOrganizationIdAndProviderAndStatus(
+    organizationId: string,
+    provider: string,
+    status: string,
+  ): Promise<TaskManagementConnection | null>;
+}

package/src/models/task-management-connection/index.js

@@ -0,0 +1,21 @@
+/*
+ * 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 TaskManagementConnection from './task-management-connection.model.js';
+import TaskManagementConnectionCollection from './task-management-connection.collection.js';
+import { validateMetadata } from './metadata-validator.js';
+
+export {
+  TaskManagementConnection,
+  TaskManagementConnectionCollection,
+  validateMetadata,
+};

package/src/models/task-management-connection/metadata-validator.js

@@ -0,0 +1,97 @@
+/*
+ * 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 { ValidationError } from '../../errors/index.js';
+
+// UUID regex used by the spec for cloudId format validation.
+const UUID_REGEX = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+
+/**
+ * Per-provider metadata schemas (mirrors spec §Metadata Validation Strategy).
+ *
+ * Each schema defines:
+ *   required   — fields that MUST be present
+ *   properties — per-field validators (functions that return an error string or null)
+ *   allowed    — exhaustive list of permitted keys (enforces additionalProperties: false)
+ *
+ * Design: plain JS instead of ajv so no new production dependency is needed.
+ * The logic is equivalent to the spec's JSON Schema: required fields, a UUID
+ * pattern constraint, and additionalProperties: false.
+ */
+// v1: only jira_cloud is supported. Add jira_corp, asana, workfront schemas here
+// when the corresponding provider value is added to TaskManagementConnection.PROVIDERS.
+const METADATA_SCHEMAS = {
+  jira_cloud: {
+    // Aligns with mysticat-data-service PR #720:
+    //   - cloudId (required) is Atlassian's stable workspace UUID used to build API URLs;
+    //     enforced as UUID format by a DB CHECK constraint.
+    //   - scopes (optional) is the array from the Atlassian accessible-resources response;
+    //     stored so permission gaps can be detected without re-calling Atlassian (e.g. missing
+    //     manage:jira-webhook when v2 webhooks land).
+    //   - siteName and siteUrl are NOT stored in metadata — they live in the dedicated
+    //     display_name and instance_url columns (see PR #720 mysticat-data-service).
+    required: ['cloudId'],
+    allowed: new Set(['cloudId', 'scopes']),
+    properties: {
+      cloudId: (v) => (UUID_REGEX.test(v) ? null : 'cloudId must be a valid UUID'),
+      scopes: (v) => (Array.isArray(v) && v.every((s) => typeof s === 'string')
+        ? null
+        : 'scopes must be an array of strings'),
+    },
+  },
+};
+
+/**
+ * Validates provider-specific connection metadata before a DB write.
+ *
+ * Called on connection INSERT and UPDATE (auth-service path and future edit API).
+ * Unknown providers are rejected — no silent passthrough.
+ *
+ * @param {string} provider - e.g. 'jira_cloud'
+ * @param {object} metadata - The JSONB metadata object to validate
+ * @throws {ValidationError} On missing fields, wrong types, unknown keys, or unknown provider
+ */
+export function validateMetadata(provider, metadata) {
+  const schema = METADATA_SCHEMAS[provider];
+  if (!schema) {
+    // Providers without a schema (asana, workfront) are v2 placeholders — reject
+    // all writes until a schema is defined so incomplete data never reaches the DB.
+    throw new ValidationError(`No metadata schema for provider: ${provider}`);
+  }
+
+  if (metadata === null || metadata === undefined || typeof metadata !== 'object' || Array.isArray(metadata)) {
+    throw new ValidationError('metadata must be a non-null object');
+  }
+
+  const { required, allowed, properties } = schema;
+
+  for (const field of required) {
+    if (metadata[field] === undefined || metadata[field] === null) {
+      throw new ValidationError(`metadata.${field} is required`);
+    }
+  }
+
+  for (const [field, validate] of Object.entries(properties)) {
+    if (metadata[field] !== undefined) {
+      const err = validate(metadata[field]);
+      if (err) {
+        throw new ValidationError(`Invalid metadata: ${err}`);
+      }
+    }
+  }
+
+  // additionalProperties: false — reject any key not in the allowed set
+  const extraKeys = Object.keys(metadata).filter((k) => !allowed.has(k));
+  if (extraKeys.length > 0) {
+    throw new ValidationError(`Unexpected metadata properties for ${provider}: ${extraKeys.join(', ')}`);
+  }
+}

package/src/models/task-management-connection/task-management-connection.collection.js

@@ -0,0 +1,61 @@
+/*
+ * 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 { isValidUUID } from '@adobe/spacecat-shared-utils';
+
+import { ValidationError } from '../../errors/index.js';
+import BaseCollection from '../base/base.collection.js';
+import TaskManagementConnection from './task-management-connection.model.js';
+
+/**
+ * TaskManagementConnectionCollection — manages TaskManagementConnection entities.
+ *
+ * Key query the ticket-creation API relies on:
+ *   `findActiveByOrganizationAndProvider(orgId, provider)` — returns the single
+ *   active connection for a given org + provider pair, or null if none exists.
+ *
+ * @class TaskManagementConnectionCollection
+ * @extends BaseCollection
+ */
+class TaskManagementConnectionCollection extends BaseCollection {
+  static COLLECTION_NAME = 'TaskManagementConnectionCollection';
+
+  /**
+   * Returns the single active connection for an organization and provider, or
+   * null when the org has not connected that provider (or the connection is
+   * in a degraded / disconnected state).
+   *
+   * The API layer calls this before every ticket-creation request and returns
+   * 409 Conflict when no active connection is found.
+   *
+   * @param {string} organizationId - The organization UUID.
+   * @param {string} provider - The provider key, e.g. 'jira_cloud'.
+   * @returns {Promise<TaskManagementConnection|null>}
+   * @throws {ValidationError} When organizationId or provider is missing.
+   */
+  async findActiveByOrganizationAndProvider(organizationId, provider) {
+    if (!isValidUUID(organizationId)) {
+      throw new ValidationError('organizationId must be a valid UUID', this);
+    }
+    if (!provider) {
+      throw new ValidationError('provider is required', this);
+    }
+
+    return this.findByOrganizationIdAndProviderAndStatus(
+      organizationId,
+      provider,
+      TaskManagementConnection.STATUSES.ACTIVE,
+    );
+  }
+}
+
+export default TaskManagementConnectionCollection;

package/src/models/task-management-connection/task-management-connection.model.js

@@ -0,0 +1,119 @@
+/*
+ * 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';
+
+/**
+ * TaskManagementConnection — one OAuth connection from an organization to a
+ * task-management provider (e.g. Jira Cloud).
+ *
+ * Status lifecycle (per architecture spec):
+ *   active           → tokens are valid, tickets can be created
+ *   disabled         → admin-disabled; no tickets until re-enabled
+ *   requires_reauth  → refresh token expired/revoked, user must reconnect
+ *   error            → repeated API failures; connection degraded
+ *   disconnected     → explicitly deleted by the user (v1 soft-delete)
+ *
+ * Provider-specific config lives in `metadata` as jsonb (jira_cloud: { cloudId, scopes }).
+ * Display fields (siteName, siteUrl) live in the dedicated displayName/instanceUrl columns.
+ *
+ * @class TaskManagementConnection
+ * @extends BaseModel
+ */
+class TaskManagementConnection extends BaseModel {
+  static ENTITY_NAME = 'TaskManagementConnection';
+
+  /** Supported task-management providers. */
+  static PROVIDERS = {
+    JIRA_CLOUD: 'jira_cloud',
+  };
+
+  /**
+   * Connection health statuses (per architecture spec PR #150).
+   *
+   * DISCONNECTED is a v1 extension — it represents the "deleted" lifecycle
+   * event as a soft-delete so audit history is preserved. The spec hard-deletes
+   * the row; v1 keeps it with status='disconnected' until a GC job removes it.
+   */
+  static STATUSES = {
+    ACTIVE: 'active',
+    DISABLED: 'disabled',
+    REQUIRES_REAUTH: 'requires_reauth',
+    ERROR: 'error',
+    DISCONNECTED: 'disconnected',
+  };
+
+  /**
+   * Returns true when this connection is healthy and ready to create tickets.
+   *
+   * @returns {boolean}
+   */
+  isActive() {
+    return this.getStatus() === TaskManagementConnection.STATUSES.ACTIVE;
+  }
+
+  /**
+   * Marks the connection as active. Called by auth-service after a successful
+   * re-authorization to restore a connection from requires_reauth state.
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markActive() {
+    this.setStatus(TaskManagementConnection.STATUSES.ACTIVE);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as requiring re-authentication (e.g. after a failed
+   * token refresh). Persists immediately so other services see the degraded
+   * state without waiting for the next GC cycle.
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markRequiresReauth() {
+    this.setStatus(TaskManagementConnection.STATUSES.REQUIRES_REAUTH);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as disabled (e.g. admin-disabled).
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markDisabled() {
+    this.setStatus(TaskManagementConnection.STATUSES.DISABLED);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as in an error state (repeated API failures).
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markError() {
+    this.setStatus(TaskManagementConnection.STATUSES.ERROR);
+    return this.save();
+  }
+
+  /**
+   * Marks the connection as disconnected (user-initiated soft-delete).
+   * v1 preserves the row for audit; a GC job handles eventual hard deletion.
+   *
+   * @returns {Promise<TaskManagementConnection>}
+   */
+  async markDisconnected() {
+    this.setStatus(TaskManagementConnection.STATUSES.DISCONNECTED);
+    return this.save();
+  }
+}
+
+export default TaskManagementConnection;