@open-mercato/core 0.6.4-develop.4371.1.8f3030407e → 0.6.4

package/generated/entities/workflow_event/index.ts

@@ -1,6 +1,7 @@
 export const id = "id";
 export const workflow_instance_id = "workflow_instance_id";
 export const step_instance_id = "step_instance_id";
+export const branch_instance_id = "branch_instance_id";
 export const event_type = "event_type";
 export const event_data = "event_data";
 export const occurred_at = "occurred_at";

package/generated/entities/workflow_instance/index.ts

@@ -14,6 +14,7 @@ export const cancelled_at = "cancelled_at";
 export const error_message = "error_message";
 export const error_details = "error_details";
 export const pending_transition = "pending_transition";
+export const active_fork_step_id = "active_fork_step_id";
 export const retry_count = "retry_count";
 export const tenant_id = "tenant_id";
 export const organization_id = "organization_id";

package/generated/entities.ids.generated.ts

@@ -28,6 +28,7 @@ export const M = {
     "data_sync": "data_sync",
     "sync_excel": "sync_excel",
     "messages": "messages",
+    "communication_channels": "communication_channels",
     "translations": "translations",
     "inbox_ops": "inbox_ops",
     "payment_gateways": "payment_gateways",
@@ -179,6 +180,7 @@ export const M = {
     "workflows": {
       "workflow_definition": "workflows:workflow_definition",
       "workflow_instance": "workflows:workflow_instance",
+      "workflow_branch_instance": "workflows:workflow_branch_instance",
       "step_instance": "workflows:step_instance",
       "user_task": "workflows:user_task",
       "workflow_event": "workflows:workflow_event",
@@ -243,6 +245,16 @@ export const M = {
       "message_access_token": "messages:message_access_token",
       "message_confirmation": "messages:message_confirmation"
     },
+    "communication_channels": {
+      "communication_channel": "communication_channels:communication_channel",
+      "external_conversation": "communication_channels:external_conversation",
+      "external_message": "communication_channels:external_message",
+      "message_channel_link": "communication_channels:message_channel_link",
+      "channel_thread_mapping": "communication_channels:channel_thread_mapping",
+      "message_reaction": "communication_channels:message_reaction",
+      "channel_thread_token": "communication_channels:channel_thread_token",
+      "channel_ingest_dead_letter": "communication_channels:channel_ingest_dead_letter"
+    },
     "translations": {
       "entity_translation": "translations:entity_translation"
     },

package/generated/entity-fields-registry.ts

@@ -366,6 +366,63 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "created_at": "created_at",
       "updated_at": "updated_at"
     },
+    "channel_ingest_dead_letter": {
+      "id": "id",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "channel_id": "channel_id",
+      "provider_key": "provider_key",
+      "external_uid": "external_uid",
+      "external_message_id": "external_message_id",
+      "error_class": "error_class",
+      "error_message": "error_message",
+      "raw_body": "raw_body",
+      "created_at": "created_at"
+    },
+    "channel_thread_mapping": {
+      "id": "id",
+      "external_conversation_id": "external_conversation_id",
+      "message_thread_id": "message_thread_id",
+      "channel_id": "channel_id",
+      "provider_key": "provider_key",
+      "external_thread_ref": "external_thread_ref",
+      "assigned_user_id": "assigned_user_id",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "created_at": "created_at",
+      "updated_at": "updated_at"
+    },
+    "channel_thread_token": {
+      "id": "id",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "message_thread_id": "message_thread_id",
+      "token": "token",
+      "created_at": "created_at",
+      "last_seen_at": "last_seen_at"
+    },
+    "communication_channel": {
+      "id": "id",
+      "provider_key": "provider_key",
+      "channel_type": "channel_type",
+      "display_name": "display_name",
+      "external_identifier": "external_identifier",
+      "credentials_ref": "credentials_ref",
+      "capabilities": "capabilities",
+      "is_active": "is_active",
+      "user_id": "user_id",
+      "is_primary": "is_primary",
+      "poll_interval_seconds": "poll_interval_seconds",
+      "last_polled_at": "last_polled_at",
+      "status": "status",
+      "last_error": "last_error",
+      "channel_state": "channel_state",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "created_at": "created_at",
+      "updated_at": "updated_at",
+      "deleted_at": "deleted_at"
+    },
     "currency": {
       "id": "id",
       "organization_id": "organization_id",
@@ -679,6 +736,8 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "interaction_type": "interaction_type",
       "title": "title",
       "body": "body",
+      "external_message_id": "external_message_id",
+      "channel_provider_key": "channel_provider_key",
       "status": "status",
       "scheduled_at": "scheduled_at",
       "occurred_at": "occurred_at",
@@ -811,6 +870,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "tenant_id": "tenant_id",
       "address_format": "address_format",
       "stuck_threshold_days": "stuck_threshold_days",
+      "dictionary_sort_modes": "dictionary_sort_modes",
       "created_at": "created_at",
       "updated_at": "updated_at"
     },
@@ -967,6 +1027,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "is_system": "is_system",
       "is_active": "is_active",
       "manager_visibility": "manager_visibility",
+      "entry_sort_mode": "entry_sort_mode",
       "created_at": "created_at",
       "updated_at": "updated_at",
       "deleted_at": "deleted_at"
@@ -1077,6 +1138,32 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "updated_at": "updated_at",
       "deleted_at": "deleted_at"
     },
+    "external_conversation": {
+      "id": "id",
+      "channel_id": "channel_id",
+      "external_conversation_id": "external_conversation_id",
+      "subject": "subject",
+      "contact_person_id": "contact_person_id",
+      "assigned_user_id": "assigned_user_id",
+      "last_message_at": "last_message_at",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "created_at": "created_at",
+      "updated_at": "updated_at"
+    },
+    "external_message": {
+      "id": "id",
+      "channel_id": "channel_id",
+      "conversation_id": "conversation_id",
+      "external_message_id": "external_message_id",
+      "direction": "direction",
+      "sender_identifier": "sender_identifier",
+      "sender_display_name": "sender_display_name",
+      "provider_timestamp": "provider_timestamp",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "created_at": "created_at"
+    },
     "feature_toggle": {
       "id": "id",
       "identifier": "identifier",
@@ -1218,6 +1305,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
     "inbox_settings": {
       "id": "id",
       "inbox_address": "inbox_address",
+      "webhook_secret": "webhook_secret",
       "is_active": "is_active",
       "working_language": "working_language",
       "organization_id": "organization_id",
@@ -1258,6 +1346,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "credentials": "credentials",
       "organization_id": "organization_id",
       "tenant_id": "tenant_id",
+      "user_id": "user_id",
       "created_at": "created_at",
       "updated_at": "updated_at",
       "deleted_at": "deleted_at"
@@ -1321,6 +1410,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "source_entity_id": "source_entity_id",
       "external_email": "external_email",
       "external_email_hash": "external_email_hash",
+      "idempotency_key": "idempotency_key",
       "external_name": "external_name",
       "external_email_sent_at": "external_email_sent_at",
       "external_email_failed_at": "external_email_failed_at",
@@ -1336,6 +1426,23 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "use_count": "use_count",
       "created_at": "created_at"
     },
+    "message_channel_link": {
+      "id": "id",
+      "message_id": "message_id",
+      "external_conversation_id": "external_conversation_id",
+      "external_message_id": "external_message_id",
+      "provider_key": "provider_key",
+      "channel_type": "channel_type",
+      "direction": "direction",
+      "delivery_status": "delivery_status",
+      "channel_payload": "channel_payload",
+      "channel_content_type": "channel_content_type",
+      "interactive_state": "interactive_state",
+      "channel_metadata": "channel_metadata",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "created_at": "created_at"
+    },
     "message_confirmation": {
       "id": "id",
       "message_id": "message_id",
@@ -1359,6 +1466,19 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "entity_snapshot": "entity_snapshot",
       "created_at": "created_at"
     },
+    "message_reaction": {
+      "id": "id",
+      "message_id": "message_id",
+      "emoji": "emoji",
+      "reacted_by_user_id": "reacted_by_user_id",
+      "reacted_by_external_id": "reacted_by_external_id",
+      "reacted_by_display_name": "reacted_by_display_name",
+      "provider_key": "provider_key",
+      "external_reaction_id": "external_reaction_id",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "created_at": "created_at"
+    },
     "message_recipient": {
       "id": "id",
       "message_id": "message_id",
@@ -1594,6 +1714,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "name": "name",
       "tenant_id": "tenant_id",
       "created_at": "created_at",
+      "updated_at": "updated_at",
       "deleted_at": "deleted_at"
     },
     "role_acl": {
@@ -2547,6 +2668,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
     "step_instance": {
       "id": "id",
       "workflow_instance_id": "workflow_instance_id",
+      "branch_instance_id": "branch_instance_id",
       "step_id": "step_id",
       "step_name": "step_name",
       "step_type": "step_type",
@@ -2686,6 +2808,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "is_confirmed": "is_confirmed",
       "last_login_at": "last_login_at",
       "created_at": "created_at",
+      "updated_at": "updated_at",
       "deleted_at": "deleted_at"
     },
     "user_acl": {
@@ -2737,6 +2860,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "id": "id",
       "workflow_instance_id": "workflow_instance_id",
       "step_instance_id": "step_instance_id",
+      "branch_instance_id": "branch_instance_id",
       "task_name": "task_name",
       "description": "description",
       "status": "status",
@@ -2766,6 +2890,26 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "tenant_id": "tenant_id",
       "processed_at": "processed_at"
     },
+    "workflow_branch_instance": {
+      "id": "id",
+      "workflow_instance_id": "workflow_instance_id",
+      "fork_step_id": "fork_step_id",
+      "join_step_id": "join_step_id",
+      "branch_key": "branch_key",
+      "parent_branch_id": "parent_branch_id",
+      "current_step_id": "current_step_id",
+      "status": "status",
+      "context_namespace": "context_namespace",
+      "pending_transition": "pending_transition",
+      "error_message": "error_message",
+      "error_details": "error_details",
+      "started_at": "started_at",
+      "completed_at": "completed_at",
+      "tenant_id": "tenant_id",
+      "organization_id": "organization_id",
+      "created_at": "created_at",
+      "updated_at": "updated_at"
+    },
     "workflow_definition": {
       "id": "id",
       "workflow_id": "workflow_id",
@@ -2790,6 +2934,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "id": "id",
       "workflow_instance_id": "workflow_instance_id",
       "step_instance_id": "step_instance_id",
+      "branch_instance_id": "branch_instance_id",
       "event_type": "event_type",
       "event_data": "event_data",
       "occurred_at": "occurred_at",
@@ -2831,6 +2976,7 @@ export const entityFieldsRegistry: Record<string, Record<string, string>> = {
       "error_message": "error_message",
       "error_details": "error_details",
       "pending_transition": "pending_transition",
+      "active_fork_step_id": "active_fork_step_id",
       "retry_count": "retry_count",
       "tenant_id": "tenant_id",
       "organization_id": "organization_id",

package/jest.config.cjs

@@ -9,9 +9,13 @@ module.exports = {
   rootDir: '.',
   moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json'],
   moduleNameMapper: {
+    '^#generated/entities\\.ids\\.generated$': '<rootDir>/jest.mocks/entities.ids.generated.js',
     '^#generated/(.*)$': '<rootDir>/generated/$1',
+    '^@open-mercato/core/generated/entities\\.ids\\.generated$': '<rootDir>/jest.mocks/entities.ids.generated.js',
     '^@open-mercato/core/generated/(.*)$': '<rootDir>/generated/$1',
     '^@open-mercato/core/(.*)$': '<rootDir>/src/$1',
+    '^@open-mercato/cache$': '<rootDir>/../cache/src/index.ts',
+    '^@open-mercato/cache/(.*)$': '<rootDir>/../cache/src/$1',
     '^@open-mercato/shared/(.*)$': '<rootDir>/../shared/src/$1',
     '^@open-mercato/ui/(.*)$': '<rootDir>/../ui/src/$1',
     '^@open-mercato/ai-assistant/(.*)$': '<rootDir>/../ai-assistant/src/$1',

package/jest.mocks/entities.ids.generated.js

@@ -0,0 +1,9 @@
+const createEntityProxy = (moduleId) => new Proxy({}, {
+  get: (_target, prop) => (typeof prop === 'string' ? `${moduleId}:${prop}` : undefined),
+})
+
+const E = new Proxy({}, {
+  get: (_target, prop) => (typeof prop === 'string' ? createEntityProxy(prop) : undefined),
+})
+
+module.exports = { E, M: E }

package/jest.setup.ts

@@ -18,6 +18,23 @@ if (typeof globalThis.WritableStream === 'undefined') {
   ;(globalThis as any).WritableStream = WritableStream
 }
 
+// jsdom doesn't implement `window.matchMedia`. Components that read viewport
+// breakpoints (e.g. `useIsMobile`, `CollapsibleZoneLayout`) call it during
+// render via `useSyncExternalStore`, which throws without this shim. Default to
+// "not matching" (desktop) — tests that need a specific breakpoint override it.
+if (typeof window !== 'undefined' && typeof window.matchMedia !== 'function') {
+  ;(window as any).matchMedia = (query: string) => ({
+    matches: false,
+    media: query,
+    onchange: null,
+    addEventListener: () => {},
+    removeEventListener: () => {},
+    addListener: () => {},
+    removeListener: () => {},
+    dispatchEvent: () => false,
+  })
+}
+
 jest.mock('react-markdown', () => ({
   __esModule: true,
   default: ({ children }: { children?: unknown }) => children ?? null,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.6.4-develop.4371.1.8f3030407e",
+  "version": "0.6.4",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -227,40 +227,43 @@
     }
   },
   "dependencies": {
-    "@mikro-orm/core": "^7.1.3",
-    "@mikro-orm/decorators": "^7.1.3",
-    "@mikro-orm/postgresql": "^7.1.3",
+    "@mikro-orm/core": "^7.1.4",
+    "@mikro-orm/decorators": "^7.1.4",
+    "@mikro-orm/postgresql": "^7.1.4",
     "@xyflow/react": "^12.11.0",
-    "ai": "^6.0.194",
+    "ai": "^6.0.197",
     "date-fns": "4.4.0",
     "date-fns-tz": "^3.2.0",
     "html-to-text": "^10.0.0",
     "mammoth": "^1.9.0",
     "pdfjs-dist": "^6.0.227",
-    "semver": "^7.8.1",
+    "resend": "^6.12.4",
+    "sanitize-html": "^2.13.0",
+    "semver": "^7.8.2",
     "svix": "^1.95.1",
     "ts-pattern": "^5.0.0",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.6.4-develop.4371.1.8f3030407e",
-    "@open-mercato/shared": "0.6.4-develop.4371.1.8f3030407e",
-    "@open-mercato/ui": "0.6.4-develop.4371.1.8f3030407e",
+    "@open-mercato/ai-assistant": "0.6.4",
+    "@open-mercato/shared": "0.6.4",
+    "@open-mercato/ui": "0.6.4",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.6.4-develop.4371.1.8f3030407e",
-    "@open-mercato/shared": "0.6.4-develop.4371.1.8f3030407e",
-    "@open-mercato/ui": "0.6.4-develop.4371.1.8f3030407e",
+    "@open-mercato/ai-assistant": "0.6.4",
+    "@open-mercato/shared": "0.6.4",
+    "@open-mercato/ui": "0.6.4",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",
     "@types/chance": "^1.1.8",
     "@types/html-to-text": "^9.0.4",
     "@types/jest": "^30.0.0",
-    "@types/react": "^19.2.16",
+    "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
+    "@types/sanitize-html": "^2.13.0",
     "@types/semver": "^7.5.8",
     "chance": "^1.1.13",
     "jest": "^30.4.2",
@@ -276,6 +279,5 @@
     "type": "git",
     "url": "https://github.com/open-mercato/open-mercato",
     "directory": "packages/core"
-  },
-  "stableVersion": "0.6.3"
+  }
 }

package/src/helpers/integration/api.ts

@@ -82,13 +82,26 @@ export async function apiRequest(
   request: APIRequestContext,
   method: string,
   path: string,
-  options: { token: string; data?: unknown },
+  options: { token: string; data?: unknown; timeout?: number },
 ) {
   const headers = {
     Authorization: `Bearer ${options.token}`,
     'Content-Type': 'application/json',
   };
-  return request.fetch(resolveUrl(path), { method, headers, data: options.data });
+  const timeout = options.timeout ?? 30_000;
+  let lastError: unknown = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await request.fetch(resolveUrl(path), { method, headers, data: options.data, timeout });
+    } catch (error) {
+      lastError = error;
+      const message = error instanceof Error ? error.message : '';
+      const retryable = /timeout|idle-session|socket|ECONNRESET|Target page, context or browser has been closed/i.test(message);
+      if (!retryable || attempt === 1) throw error;
+      await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+  }
+  throw lastError;
 }
 
 export async function postForm(

package/src/helpers/integration/authFixtures.ts

@@ -1,7 +1,10 @@
 import { expect, type APIRequestContext } from '@playwright/test';
-import { apiRequest } from './api';
+import { apiRequest, getAuthToken } from './api';
 import { expectId, readJsonSafe } from './generalFixtures';
 
+// Re-exported so tests can import auth helpers from a single fixtures module.
+export { getAuthToken };
+
 const BASE_URL = process.env.BASE_URL?.trim() || null;
 
 function resolveUrl(path: string): string {

package/src/helpers/integration/communicationChannelsFixtures.ts

@@ -0,0 +1,130 @@
+import { expect, type APIRequestContext } from '@playwright/test';
+import { apiRequest } from './api';
+import { expectId, readJsonSafe } from './generalFixtures';
+
+/**
+ * Communication-channels integration fixtures.
+ *
+ * These drive the TEST-ONLY seed endpoint `POST /api/communication_channels/test-seed`,
+ * which is gated by `OM_ENABLE_TEST_CHANNEL_SEEDING` (inert/404 in production). Use
+ * {@link isChannelSeedingAvailable} to skip tests when the gate is off rather than
+ * failing them.
+ */
+
+export type SeedAddressField =
+  | string
+  | { address: string; name?: string }
+  | Array<string | { address: string; name?: string }>;
+
+const TEST_SEED_PATH = '/api/communication_channels/test-seed';
+
+/**
+ * Probe whether the env-gated test-seed endpoint is enabled in the target app.
+ * Returns false when the route answers 404 (flag off) so callers can `test.skip`.
+ * The caller's token must hold `communication_channels.connect_user_channel`.
+ */
+export async function isChannelSeedingAvailable(
+  request: APIRequestContext,
+  token: string,
+): Promise<boolean> {
+  // A malformed body returns 422 when the gate is ON and 404 when it is OFF.
+  const response = await apiRequest(request, 'POST', TEST_SEED_PATH, {
+    token,
+    data: { action: '__probe__' },
+  });
+  return response.status() !== 404;
+}
+
+/**
+ * Seed a connected, network-free `__test_seed__` channel owned by the caller.
+ * Returns the new channel id. Tear down with {@link deleteChannelIfExists}.
+ */
+export async function seedConnectedChannel(
+  request: APIRequestContext,
+  token: string,
+  input: { displayName?: string; externalIdentifier?: string } = {},
+): Promise<string> {
+  const response = await apiRequest(request, 'POST', TEST_SEED_PATH, {
+    token,
+    data: { action: 'connect-channel', ...input },
+  });
+  expect(
+    response.status(),
+    'POST /api/communication_channels/test-seed (connect-channel) should return 201',
+  ).toBe(201);
+  const body = await readJsonSafe<{ channelId?: string }>(response);
+  return expectId(body?.channelId, 'connect-channel response should include channelId');
+}
+
+/**
+ * Seed an inbound `MessageChannelLink` for `channelId` and emit
+ * `communication_channels.message.received` through the real event bus. The
+ * persistent customers link-channel-message-received subscriber is enqueued to
+ * the `events` queue — drain it with `drainIntegrationQueue('events')`.
+ *
+ * Returns the created link + message ids (the message id is the platform
+ * `messages.message` id, usable as `messageThreadId` to thread a follow-up).
+ *
+ * Pass `createThreadMapping: true` to also seed a `ChannelThreadMapping` for the
+ * thread — required before exercising the reaction (`/messages/[id]/reactions`)
+ * and thread-assign (`/threads/[id]/assign`) routes, which resolve the owning
+ * channel through that mapping.
+ */
+export async function seedInboundMessage(
+  request: APIRequestContext,
+  token: string,
+  input: {
+    channelId: string;
+    from?: SeedAddressField;
+    to?: SeedAddressField;
+    cc?: SeedAddressField;
+    subject?: string;
+    bodyText?: string;
+    messageId?: string;
+    inReplyTo?: string;
+    references?: string[];
+    messageThreadId?: string;
+    providerKey?: string;
+    createThreadMapping?: boolean;
+  },
+): Promise<{ channelLinkId: string; messageId: string; conversationId: string }> {
+  const response = await apiRequest(request, 'POST', TEST_SEED_PATH, {
+    token,
+    data: { action: 'emit-inbound', ...input },
+  });
+  expect(
+    response.status(),
+    'POST /api/communication_channels/test-seed (emit-inbound) should return 201',
+  ).toBe(201);
+  const body = await readJsonSafe<{
+    channelLinkId?: string;
+    messageId?: string;
+    conversationId?: string;
+  }>(response);
+  return {
+    channelLinkId: expectId(body?.channelLinkId, 'emit-inbound response should include channelLinkId'),
+    messageId: expectId(body?.messageId, 'emit-inbound response should include messageId'),
+    conversationId: expectId(
+      body?.conversationId,
+      'emit-inbound response should include conversationId',
+    ),
+  };
+}
+
+/**
+ * Best-effort delete of a seeded channel via the owner-scoped DELETE route.
+ * Safe to call with a null id in `finally`.
+ */
+export async function deleteChannelIfExists(
+  request: APIRequestContext,
+  token: string | null,
+  channelId: string | null,
+): Promise<void> {
+  if (!token || !channelId) return;
+  await apiRequest(
+    request,
+    'DELETE',
+    `/api/communication_channels/channels/${encodeURIComponent(channelId)}`,
+    { token },
+  ).catch(() => undefined);
+}

package/src/helpers/integration/crudFormFields.ts

@@ -0,0 +1,48 @@
+import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean';
+
+/**
+ * Pure, runner-agnostic helpers for the CrudForm field-persistence sweep (umbrella #2466).
+ *
+ * Kept free of any `@playwright/test` import so this logic is unit-testable under jest.
+ * The Playwright harness (`crudFormPersistence.ts`) re-exports everything here.
+ */
+
+export const CRUDFORM_EXTENSION_TESTS_DISABLED_ENV = 'OM_INTEGRATION_CRUDFORM_EXTENSION_TESTS_DISABLED';
+
+export type CrudRecord = Record<string, unknown>;
+
+/**
+ * Reads the sweep disable flag. Default `false` so the sweep runs unless explicitly turned off
+ * via `OM_INTEGRATION_CRUDFORM_EXTENSION_TESTS_DISABLED=1` (or `true`/`yes`/`on`).
+ */
+export function crudFormExtensionTestsDisabled(env: NodeJS.ProcessEnv = process.env): boolean {
+  return parseBooleanWithDefault(env[CRUDFORM_EXTENSION_TESTS_DISABLED_ENV], false);
+}
+
+/**
+ * Resolves a custom-field value from a CRUD response record, tolerating every shape the
+ * platform emits: bare keys under `customValues`, top-level `cf_<name>` / `cf:<name>`, or a
+ * `customFields` definition array carrying `value`. Returns `undefined` when absent.
+ */
+export function getCustomFieldValue(record: CrudRecord, fieldName: string): unknown {
+  const customValues = record.customValues;
+  if (customValues && typeof customValues === 'object' && fieldName in (customValues as CrudRecord)) {
+    return (customValues as CrudRecord)[fieldName];
+  }
+  const prefixedUnderscore = record[`cf_${fieldName}`];
+  if (prefixedUnderscore !== undefined) return prefixedUnderscore;
+  const prefixedColon = record[`cf:${fieldName}`];
+  if (prefixedColon !== undefined) return prefixedColon;
+  const customFields = record.customFields;
+  if (Array.isArray(customFields)) {
+    const match = customFields.find((entry) => {
+      if (!entry || typeof entry !== 'object') return false;
+      const candidate = entry as CrudRecord;
+      return candidate.key === fieldName || candidate.id === fieldName || candidate.name === fieldName;
+    });
+    if (match && typeof match === 'object') {
+      return (match as CrudRecord).value;
+    }
+  }
+  return undefined;
+}